Difference between revisions of "Legacy UART-RF-Protocol"

Revision as of 11:46, 8 March 2011

Overview

The Demo-Software implemets an UART-to-Radio protocol. The UART has to be connected to UART1 of the ICradio OEM and the Baudrate hast to be set to 115200Baud,8,N,1. For an easy use the pakets to the uart have to be send as hex-values as ASCII, meaning 0x00 ia send as "00". Only '0'-'9' and 'A'-'F' are accepted letters. Additionaly there is an 'Magic Word' - the letter 'S'. The 'S' is used as sync byte to start a packet.

UART packets to radio

The packets to the UART alway have a fixed sceme:

packets to uart of the radio

first letter is the 'S'
followed by 2 bytes length of the packet (N + 1(type) +16(address))
followed by 16 bytes IPv6 address of the destination, the IPv6 address ::1 is reserved for the Local Host. Packets to the ocal host are not sent over radio, but they are commands to the module.
followed by 1 type-byte, that determines the type of the packet. When a module receives the packet, it decides with the type how to handle the packet data. There are several packet types pre-defined - as seen below.
followed by N data bytes.

Example 1 - Packet to the UART:

S0015FF0200000000000000000000000000010012345678

This commad sends an Broadcast data packet with 4 bytes of data =0x12345678.

the length is 16Bytes(address) + 1Byte(type) + 4Bytes(data) = 21Bytes = 0x15
the address FF020000000000000000000000000001 is the IPv6 broadcast address
type 0x00 means that the packet is a data packet, see the pre-defined packet types below
the data are 0x12 0x34 0x56 0x78

UART packets from radio

When the radio sends packets via UART, theese packets also have a fixed sceme:

packets from uart of the radio

first letter is the 'S'
followed by 2 bytes length of the packet (N + 1(type) +16(address))
followed by 16 bytes IPv6 address of the destination, the IPv6 address ::1 is reserved for the Local Host. Packets to the ocal host are not sent over radio, but they are commands to the module.
followed by 1 type-byte, that determines the type of the packet. When a module receives the packet, it decides with the type how to handle the packet data. There are several packet types pre-defined - as seen below
followed by N data bytes
followed by one byte RSSI (Radio Signal Strength Indicator) as 8-bit signed integer

NOTE: the RSSI byte is not counted to the length of the packet!

every packet from the radio closes with an <CR><LF> (hex values 0x13 0x10). So te user can just read one line from the uart and gets the hole packet.

Example 2 - Packet from the UART:

S0014FE80000000000000001FE001000000030000C901C9

The Radio received a packet from node FE80000000000000001FE00100000003 with type=0x00 and data 0x00C901. The RSSI of the received packet was 0xC9= -55dBm

the length is 16bytes(source address) + 1byte(type) + 3Bytes(data) = 20Bytes = 0x14 (the RSSI is not counted to the length of the packet)
the address FE80000000000000001FE00100000003 is the IPv6 address of the sender
type 0x00 means that the packet is a data packet, see the pre-defined packet types below
the data are 0x12 0x34 0x56 0x78

Implemented Commands / Packet Types

The UART-RF-protocol pre-defines several types of packets (type byte in the packets). Pre-defined packet types are:

typedef enum {
 PACKET_TYPE_DATA                            = 0x00,
 PACKET_TYPE_BIND                            = 0x01,
 PACKET_TYPE_BINDACK                         = 0x02,
 PACKET_TYPE_UNBIND                          = 0x03,
 PACKET_TYPE_SETUP                           = 0x04,
 PACKET_TYPE_SETUP_ACK                       = 0x0C,
 PACKET_TYPE_DISCOVER_NETWORK                = 0x05,
 PACKET_TYPE_DISCOVER_NETWORK_REPLY          = 0x06,
 //board specific commands for ADB2001
 PACKET_TYPE_LED_DATA                        = 0x07,
 PACKET_TYPE_BTN_DATA                        = 0x08,
 //board specific commands for ICradioPlug
 PACKET_TYPE_PLUG_GET                        = 0xF0,
} PACKET_TYPE_t;

Data Packet

Binding Commands

Bind Command

The Bind command can be used to set up a point-to-point communication between two nodes. The ICradio Plug is a typical node that needs to be binded before the communication starts. To Bind a node you have to send the type-byte=0x01 with no further data.

S0011FF02000000000000000000000000000101 - Bind broadcast, this command binds all free nodes.
S0017FE80000000000000001FE5020000000C01 - Bind-unicast to address=FE80000000000000001FE5020000000C

Bind Acknowledge Packet

After receiving a bind-packet the node sends back an bind-ack packet to acknowledge the successful binding process. Tho bind-ack packet as type-byte=0x02 with no further data.

S0011FE80000000000000001FE5020000001402C3 - Bind ack from node FE80000000000000001FE50200000014 with RSSI=C3(-61bB)

Un-Bind Command

Once binded the node can be un-binded by sending a un-bind packet to it. After receiption of the un-bind command the node will fall back to the unbinded state. Then it can be binded to another node. To un-bind a node you have to send the type-byte=0x03 with no further data. Note that the un-bind command is only accepted from the binded node! This means that an unbind-broadcast will not work.

S0017FE80000000000000001FE5020000000C03 - Unbind-unicast to address=FE80000000000000001FE5020000000C

---

Setup Command

not yet implemented

Setup Acknowledge Packet

not yet implemented

Discover Network Command

S00110000000000000000000000000000000105
lenght = 0x0011 = 17 bytes
destination address = 00000000000000000000000000000001 - address = ::1 (IPv6 Local Host)
type = 0x05 = PACKET_TYPE_DISCOVER_NETWORK

This is the commad 0x05 to the Local Host. It is the command to discover the network. The module executes the stack-command for scanning the network and sets a callback-routine that is called when another node is dicovered.

Discover Network Reply Packet

When nodes are discovered, a callback routine is called. This callback routine is implemented as follows:

void rf_CallbackDiscover( unsigned char hopCount, char rssi, unsigned char  addrCount, ZWIR_IPv6Address_t*  address ) {
  uint8_t data[16];
  data[0] = hopCount;
  data[1] = rssi;
  data[2] = addrCount;
  packetHandler(SOURCE_RF, address, PACKET_TYPE_DISCOVER_NETWORK_REPLY, data, 3);
}

The callback routine sets up a data packet with the address, the hopCount and the RSSI to the discovered Node. (The additional data byte addrCount can be ignored). Then it calls the packetHandler with type=PACKET_TYPE_DISCOVER_NETWORK_REPLY to send the packet to the UART. This UART packet may look like this:

S0014FE80000000000000001FE001000000030600C901C9
  Source address = address of the received node
  type = 0x06 = PACKET_TYPE_DISCOVER_NETWORK_REPLY
  data = 3 bytes with hopcount, RSSI, addrCount(ignored)

This reply means that the node FE80000000000000001FE00100000003 is 0 hops away and is received with -33dBm signal strength.

Board specific commads

There are several Board specific commands handling useful simple commands. This simplifys the handling of the Hardware and shows the implementation of user defined commands.

Set LED Packet

This Packet is used to set the two user-LEDs on an ADB2001. The receiver for that packet may be - another node, by setting the destination address to this node's address

S0013FE80000000000000001FE00100000003070100
  Source address = address of the received node
  type = 0x07 = PACKET_TYPE_LED_DATA
  data[0] = data for LED1 (0 = off, 1=on)
  data[1] = data for LED1 (0 = off, 1=on)
This command sets the LEDs of Node S0013FE80000000000000001FE00100000003070100 to LED1=on, LED2=off

- the radio itself, by setting the destination-address = LOCAL_HOST

S001300000000000000000000000000000001070100  (set LED1=on, LED2=off)
S001300000000000000000000000000000001070001  (set LED1=off, LED2=on)

Button Pressed Packet

When the user presses the USR-Button on the ADB2001 a button-presses packet is broadcasted by the module.

Get Plug Data Packet