# Network Join protocol
Conventions Used in This Document The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 (opens new window).
# Overview
The Network Join Protocol is responsible for transporting Device Join requests.
# Join Request (ID 0)
The Join request message contains a 1 byte Join Request Header with the method used to authenticate the Device, followed by the Join Request message.
| JReqHdr 1 byte | Join Request message |
|---|
The following table details the JReqHdr message protocol numbers:
| JReqHdr | Description |
|---|---|
| 0x00 | Reserved |
| 0x01 | Device UUID |
| 0x02 - 0x99 | Reserved |
| 0xA0 - 0xEF | Proprietary |
| 0xF0 - 0xFF | Reserved |
The Proprietary protocol numbers can be used by proprietary implementations, the rest are reserved for standard and open Join Request implementation specifications.
# Device Proof of Identity (PoI) using encryption
The Proof of Identity Join request message is constructed from the Device UUID, a 8 byte nounce (random numbers) and the characters "0000join":
| JReqHdr 1 byte | Device UUID 16 bytes | Nonce 8 bytes | Zero 4 bytes | Char string: “join” 4 bytes |
|---|
The "join" chars are all lower-case 0x6a (j), 0x6f (o), 0x69 (i), 0x6e (n).
To construct the Proof of Identity, the Device encrypts the nonce, the 4 bytes with zero and the join char string with the Device encryption key using AES128-CBC. If the Network Server can successfully decrypt the 0000join phrase using the device key, then a device join is accepted and a join response is returned.
Example:
| Key | Value (Hex) |
|---|---|
| Ramdom number | 93 da 92 8d 98 47 a8 b3 3d 6d af |
| Char string: “join” | 6a 6f 69 6e |
| IV | 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f |
| PSK | ee 1b 3d c7 b2 45 5a 2a c6 c1 8b 20 d1 27 4f d7 |
| Result | d4 92 7c ac 31 a8 39 08 8a b2 5a a1 99 1d 05 ba |
# Device Proof of Identity (PoI) using plain-text
This section is under development.
# Join Response (ID 1)
The Response to a Join Request contains a status byte as well as configuration data for the Device. This includes when to send event data and when to send Status information. It also contains the network time in UTC and an optional Device Configuration data.
| JResHdr 1 byte | Status 1 byte | Addr 1 byte | Event interval 2 bytes | Status interval 2 bytes | UTC Time 4 bytes | opt. cfg 0-32 bytes |
|---|
JResHdr:
| JResHdr | Description |
|---|---|
| 0x00 | Reserved |
| 0x01 | Device UUID |
| 0x02 - 0x99 | Reserved |
| 0xA0 - 0xEF | Proprietary |
| 0xF0 - 0xFF | Reserved |
# Join Response
The Join response message status byte is the Join Response code. If this is 0 (zero) the join is allowed, else the status code will contain a non-zero value with the reason why. Status codes are as follows:
| Status | Description |
|---|---|
| 0 | Join Accepted |
| 1 | Join Rejected |
The other headers are described in this table:
| Header | Description |
|---|---|
| Addr | The network address assigned to the ED |
| Event interval | Interval, in seconds (1-65534)**, between the event messages (eg. temp=22) |
| Status interval | Interval, in seconds (1-65534)**, between the status messages in (eg. Firmware version, battery level etc). |
| UTC time | Current time that the ED will use to set it's internal RTC |
| Opt. cfg. | Optional Device specific configuration |
** The Event- and Status-interval number 0 means "disabled and/or at the it's own discretion". 65535 is reserved for future use.
The address byte is the address assigned to the ED. It will be zero if the Join is rejected. If the Join is accepted, it will contain a value between 2 and 250 that the ED MUST use as it link local address.
The aAssociation with the GW does not need to be re-negotiated. Instead the ED MUST send a status message (Network Event) every interval time. The status message is sent using the reliable protocol and this allows the following:
- If the ED does not get a respond from the GW after 3 retries, then the ED MUST re-join the network (scanning channels)
- If the ED is sending events using the unreliable (un-ack'd) protocol, then the reply from the GW allows for sending messages to the ED from the network.
The Join response SHOULD contain the current UTC Time.
# Gateway Discovery Request (ID 2)
The Gateway Discovery Request makes it possible for Devices to select a Gateway and a network to join. Devices select a frequency, modulation and a baud-rate, and either broadcast or unicasts the Gateway Discovery Request.
The payload of the request contains a 4-byte random nonce. This nonce MUST be returned by the Gateway in the Gateway Discovery Response payload, so that the device can verify the reply.
# Packet payload
| Nonce 4 bytes |
|---|
# Gateway Discovery Response (ID 3)
All Gateways that receives the Gateway Discover Request SHOULD respond with a Gateway Discovery response. This allows the requesting Device to determine the closest Gateway to connect to. Devices MAY use the Gateway Discovery Response to measure the RSSI of the received packet, in order to determine the closest gateway.
# Packet payload
| Nonce 4 bytes |
|---|