Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
A lightweight radio protocol for home automation applications
Fetching latest commit…
Cannot retrieve the latest commit at this time.
|Type||Name||Latest commit message||Commit time|
|Failed to load latest commit information.|
TinyHAN - Tiny Home Area Network -------------------------------- TinyHAN is a general purpose datagram oriented protocol for building sensor and control networks. It is similar in concept to 802.15.4, but designed to work on ultra low cost hardware such as radio modules from HopeRF (e.g. RFM22B, RFM69W). Intended for domestic applications, there is no support for meshing, reducing the code size dramatically. The protocol adopts a layered design, with this library handling the physical and MAC layers. PHY drivers are pluggable allowing interoperation between devices using different radios. There is also a test PHY using UDP multicast that enables the library to be tested on a Linux PC. The MAC provides the following key features: * Application datagram transmission with or without acknowledgement * Automatic re-transmission of unacknowledged packets * Support for two-way communication with sleeping (battery powered) nodes * Per-packet validity period * Automatic node registration and address assignment * Monitoring of node presence (heartbeat) and signal strength, notification of node loss * Optional periodic beacons to reduce transmission latency to sleeping nodes Encryption and authentication are not supported in this version, but are on the roadmap as key requirements. Also in the spec but not yet implemented is listen-before-talk (carrier-sense), to reduce the likelihood of interference between unsynchronised nodes. Library ------- The protocol is implemented as a platform-independent library targeting both small and large embedded systems. A small platform abstraction layer is used to handle OS and hardware dependencies. Currently, the library is in-use on the following targets: * Linux PC using the UDP demo PHY * Atmel AVR ATMEGA328 (bare metal) with RFM23B radio * STM32F407 running FreeRTOS, with RFM23B radio Transports ---------- TinyHAN can carry any datagram based transport protocol (e.g. 6LoWPAN should be feasible). Examples are included for: * TinyHAN application protocol - a work-in-progress binary name/value pair protocol with extermely low software overhead designed for sensing and control applications * MQTT-SN Tools ----- A GnuRadio tool is included to enable real-time debugging of a network by sniffing signals off the air. The tool works with low cost RTL-SDR dongles, or could be modified to work with other SDRs such as HackRF or FCD. Examples -------- Several examples are provided to demonstrate the use of the TinyHAN library. Note that these are not intended to be complete applications. The basic steps for implementing a TinyHAN node in a typical small embedded system are as follows: - Call phy_init() during early startup. - Call tinymac_init(¶ms) during early startup, where params is a pointer to a tinymac_params_t structure containing the node configuration. - Call tinymac_register_recv_cb to register a function to be called when an incoming application message is received. - Arrange for tinymac_tick_handler to be called every 250ms. - Arrange for phy_event_handler to be called at least whenever the radio indicates activity (e.g. after being woken by an external interrupt). - Call tinymac_send whenever the application wishes to transmit a message. To create a coordinator the tinymac_params_t structure must define coordinator=1, and tinymac_permit_attach(1) must be called to enable nodes to connect. The coordinator role supports additional callbacks to be invoked on attachment and detachment of remote nodes. Building the Sensor Example --------------------------- The AVR example in examples/sensor is designed to be built standalone (it is not for an Arduino, although it can probably be made to run on one fairly easily). It requires the AVR GCC toolchain and has been tested under Linux using the AVRDUDE programmer and a genuine Atmel AVRISP. A schematic for example hardware is included as a PDF. The demo uses a hard-coded UUID (which must be changed if more than one node is being tested in the same area) and will register with any coordinator that will permit attachment. After registration the node will transmit its battery voltage every 5 seconds, and will toggle an LED according to a value received from the coordinator. The node is configured as a sleeping device, so messages from the coordinator are buffered and can take several seconds to deliver. Total code size is a little over 5KB at present (it is likely this can be reduced through further optimisation of the TinyHAN MAC). Average current consumption was estimated to be around 80 uA with two-way communication, suggesting around 3.5 years lifetime from 2 AA cells. Further power optimisation is likely to be feasible. To build and program a board: $ make $ make program Building the PC based MQTT-SN Example ------------------------------------- This requires a third-party MQTT-SN broker running on the same machine (e.g. RSMB). RSMB can be started with the following config file (save as 'config'): trace_output protocol listener 1883 INADDR_ANY mqtts $ ./broker config Build the client and gateway: $ cd examples/mqttsn-client $ make $ cd examples/mqttsn-simple-gateway $ make Start the MQTT-SN broker and run the TinyHAN gateway in one terminal: $ cd examples/mqttsn-simple-gateway $ ./build-simplegateway/simplegateway In another terminal run an instance of the client: $ cd examples/mqttsn-client $ ./build-mqttsn_client/mqttsn_client The client will immediately register with the coordinator/gateway and attempt to connect to the MQTT-SN broker after a few seconds. The client subscribes to the following example topics: zone/1/target zone/1/message Publishing a message to either of these topics (e.g. using mqtt-sn-tools) will result in the message appearing in the client terminal. License ------- Copyright 2013-2014 Mike Stirling Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.