smart-home/README.md

Smart Home

This repository contains the description of a number of smart home devices as well as the source code for the corresponding firmware.

Compiling

Compiling the display firmware requires a rust toolchain for ARMv6m:

rustup target add thumbv6m-none-eabi

Compiling the base station software depends on the targeted board. The following steps can be used to cross-compile the software for an ARMv7 target running Armbian from a Fedora host:

1. Install the toolchain:

   sudo dnf copr enable lantw44/arm-linux-gnueabi-toolchain
   sudo dnf install arm-linux-gnueabi-gcc.x86_64
   rustup target add arm-unknown-linux-gnueabi
   

2. Configure Rust to use the ARM GCC:

   cat > ~/.cargo/config <<_EOF
   [target.arm-unknown-linux-gnueabi]
   linker = "arm-linux-gnueabi-gcc"
   rustflags = ["-Clink-args=-Wl,--dynamic-linker=/lib/ld-linux-armhf.so.3"]
   _EOF
   

3. Compile the software using the newly installed toolchain:

   cargo build --target=arm-unknown-linux-gnueabi
   

For an Ubuntu host, the following steps can be used:

1. Install the toolchain:

   sudo apt-get install gcc-arm-linux-gnueabihf
   rustup target add arm-unknown-linux-gnueabihf
   

2. Configure Rust to use the ARM GCC:

   cat > ~/.cargo/config <<_EOF
   [target.arm-unknown-linux-gnueabihf]
   linker = "arm-linux-gnueabihf-gcc"
   _EOF
   

3. Compile the software using the newly installed toolchain:

   cargo build --target=arm-unknown-linux-gnueabihf
   

Protocol

Packets are up to 32 bytes long. Most bytes are encrypted via XXTEA, except for one packet sent to the base station from a device to request a random number. The base station then replies with an encrypted packet containing a random salt value, and the device uses this salt for all further communication until the next reset, increasing the salt value by one for each packet sent. This scheme removes the need for the device to generate random numbers, as microcontrollers commonly are not capable of generation of high-quality ranodm numbers.

The packet sent from the device to the base station to request a salt consists of a single byte with the sender ID and is recognized by the base station by its length.

Packet Format

All encrypted packets follow the same scheme, with everything following after the salt being encrypted using a per-device XXTEA key hardcoded on the device and known to the base station. The packet fields are as follows, with multi-byte fields being encoded as little-endian:

1. Device ID (1 byte)
2. Remainder of salt (7 bytes)

The most significant bit of the salt value is 0 for packets from the device to the base station and 1 for packets from the base station to the device.

All fields from here on are encrypted with XXTEA, using the first 8 bytes of the packet as the salt.

1. Packet type and element count (1 byte)

The 5 least significant bits of the field encode the packet type, with the following possible values:

1. Salt: The packet is sent by the base station to the device whenever a 1-byte packet containing the device ID is received.
2. Report: The packet contains values measured by this node. The element count signals the number of values (of different types) reported by the device.
3. GetValues: Sent by a device to request values generated by other sensor nodes from the base station, or to request the current time. The element count signals the number of different values requested.
4. Values: Reply to a GetValues packet containing the requested information.

The 3 most significant bits of the field encode the element count for packets which can holt multiple elements (as described below).

1. Packet payload (always 21 bytes, padded with zero bytes)

The payload field holds the packet content, with a variable format depending on the packet type:

• Salt: The first 7 bytes of the payload hold the salt used by the sensor node from this time on.
• Report: The payload consists of a number of (value type, value)-tuples. The possible value types and the corresponding value size are listed below.
• GetValues: The payload consists of a list of value types. It is the sender’s responsibility to ensure that the resulting response fits into one packet. If too many values are requested, the base station will ignore the request.
• Values: The payload consists of a list of (value type, report time, value) tuples. The report time is the unix time of the last report of the corresponding sensor node.

1. CRC-16-CCITT checksum

Value types:

1. Time (4 bytes): The value is a unix time in seconds.
2. Temperature (2 bytes): The value is a temperature value in tenths of degrees celsius.
3. Pressure (4 bytes): The value is a pressure in pascal.
4. Humidity (2 bytes): The value is the relative humidity in tenths of a percent.

License

The hardware contained in this repository is licensed under the CERN Open Hardware Licence Version 2 - Weakly Reciprocal, and the software is licensed under the GNU General Public License v3.