
# 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. All bytes are encrypted via XXTEA. First, the
device requests a salt from the base station requests (using salt 0 for the
packet). 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 random
numbers.

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

   For GetSalt packets, the remainder of the salt is 0.

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. GetSalt: The packet is sent by the device when no salt is available. The
      base station replies with a Salt packet.
   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 hold 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. 

     TODO: Describe the network topology above and specify which payload type is
     used by which device for which purpose.

     TODO for GetValues: There should be a way for a device to request
     the value from a certain source (e.g. the termperature of the living room).

     TODO for GetValues: There should be an answer packet to signal that the
     requested source is not available.

5. CRC-16-CCITT checksum

### Value types:

0. Time (8 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.

# Data handling:

The base station collects all needed data from the sensors and other sources and
acts as a server for all devices.

- The base station shall contain a list of all devices on the network.
- The base station shall have an interface where devices can be added and removed
  from the network.
- Every sensor shall be registered using a (module id, location) tuple.
- The base station shall monitor the update rates of the devices.
- Every device shall be assigned a threshold of missed updates after which it is
  considered to be offline.
- The base station shall indicate that a device is offline if another device
  requests a report from the offline device.

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