# 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.

3. Packet type and element count (1 byte)

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

   0. Salt: The packet is sent by the base station to the device whenever a
      1-byte packet containing the device ID is received.
   1. Report: The packet contains values measured by _this_ node. The element
      count signals the number of values (of different types) reported by the
      device.
   2. 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.
   3. 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).

4. 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.

5. CRC-16-CCITT checksum

### Value types:

0. Time (4 bytes): The value is a unix time in seconds.
1. Temperature (2 bytes): The value is a temperature value in tenths of degrees
   celsius.
2. Pressure (4 bytes): The value is a pressure in pascal.
3. 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](cern_ohl_w_v2.txt), and the software is licensed under the [GNU General Public License v3](gpl-3.0.md).