doorstatus/README.md

# KrautStatus

This repository contains documentation and sources of KrautStatus. KrautStatus
is the n-th iteration of a software/hardware project to communicate whether
Jena's Krautspace is open or closed.

KrautStatus consists of three components: an Arduino-sensor-combination at the
door, a Python script on a local server, and an API file served on by web
server.

The Arduino provides the current state of the door lock upon request via UDP.
The state is determined by a reed sensor in the door lock. In addition, it
controls an RGB LED matrix shield that provides a visual indication of the door
locks's state in the room.

The python script polls the broadcast state and pushes changes to Twitter,
Mastodon and our API file.

The API file follows the [Space API](http://spaceapi.net) specification, which
includes a field indicating whether the space is open or closed.

## Arduino

### Arduino: Hardware

We measure the door's lock state using a reed switch. The switch is installed at
the bottom of hole for the deadbolt and gets triggered by a magnet glued to the
tip of the deadbolt.

The reed switch is connected to pin 0 and ground on an Arduino MKR1000. The
software sets up pin 0 (by default) with a pull up resistor. This prevents
currents induced into the long wire between switch an Arduino to trigger the pin
state.

A second component connected to the MKR1000 is an Arduino MKR RGB Shield that
provides a 7x12 RGB LED matrix. It is used to give visual feedback on the
software's current state.

While trying to connect to the configured WLAN, a vertical yellow line
oscillates between both sides of the display. When connecting to the WLAN fails,
a red cross is displayed. When the room is open all LEDs are green, and when it
is closed all LEDs are turned off (nobody should be there to see it anyway).

The following images is a schematic showing the connections between the three
components mentioned.

![a schematic of Arduino MKR1000 and all components physically connected to it, as described in the text](documentation/arduino.png)

The Arduino is powered by a USB charger.

If you need to change the schematic, adapt `documentation/arduino.tex` and run
`make`. This requires the following software and TeX libraries to be installed
on your systems:

- pdflatex
- convert from ImageMagick
- tikz
- circuitikz

### Arduino: Setup and Configuration

The sketch for our Arduino is located in `sources/arduino`. Before we flash the
Arduino with the sketch, we should adapt `config.h`. We can use either the
[Arduino IDE](https://www.arduino.cc/en/software) or the provided Makefile to
verify or flash the sketch.

For the Makefile to work,
[Arduino CLI](https://arduino.github.io/arduino-cli/latest/) has to be
installed. Use `make` for verification and `make install` to flash the board,
which needs to be connected to our PC via USB cable.

Verifying and flashing the sketch requires the installation of several
libraries.

First we need the core for the family of boards Arduino MKR1000
belongs to: Arduino SAMD Boards (or `arduino:samd`). Installation instructions
for [Arduino IDE](https://www.arduino.cc/en/guide/cores) and
[Arduino CLI](https://arduino.github.io/arduino-cli/latest/commands/arduino-cli_core_install/)
can be found in the respective documentation.

Then we need to make sure the following libraries are installed:

- ArduinoGraphics
- Arduino_MKRRGB
- uTimerLib
- WiFi101

Installed instructions for
[Arduino IDE](https://www.arduino.cc/en/guide/libraries) and
[Arduino CLI](https://arduino.github.io/arduino-cli/latest/commands/arduino-cli_lib_install/)
can be found in the respective documentation.

We assign a fixed IP address in the space's WiFi network to the Arduino's MAC
address. The MAC address gets printed to `Serial` on each start up. Once
connected to the configured WLAN, the IP address is also printed to `Serial`.
(TODO: MENTION WHERE TO FIND DOCUMENTATION FOR OUR DHCPD.)

### Arduino: UDP API

Once the Arduino has started successfully, it listens on the configured port
(see [sources/arduino/config.h](sources/arduino/config.h) for the default port)
for UDP packets and answers each incoming packet with the state of the door. The
state is encoded as a one byte integer, where `0` stands for closed and `1`
stands for open.

In `scripts` is the Python 3 script `test_udp_api.py`, which we use to test the
UDP API. It takes an IP address and optionally a port, queries the Arduino, and
prints out the result.

## In-Space Service

## Internet Service


## License

The authors of the Arduino code license the code under the AGPL 3.0 (see
`LICENSE.AGPL`). The respective authors are listed in the preambles of each
source file.

## Dependencies

The creation of the schematic image depends on the following libraries:

*TikZ* published by the copyright holders under the GPL 2, the Free
Documentation License, and the LaTeX Project Public License 1.3c

*Circuitikz* published by the copyright holders under the GPL 2 and the LaTeX
Project Public License

The Arduino code depends on the following libraries:

*Arduino SAMD Boards* published by the copyright holders under the LGPL 2.1 or later.

*SPI Master Library for Arduino Zero* published by the copyright holders under
the LGPL 2.1 or later.

*ArduinoGraphics* published by the copyright holders under the LGPL 2.1 or
later.

*Arduino_MKRRGB* published by the copyright holders under the LGPL 2.1 or later.

*uTimerLib* published by the copyright holders under the LGPL 3.

*WiFi101* published by the copyright holders under the
LGPL 2.1 or later.