Implement and document Arduino software

README.md

@@ -21,24 +21,126 @@ includes a field indicating whether the space is open or closed.
 
 ## Arduino
 
-## Python Script
+### 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
 
-## API
 
 ## 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 in the preambles of
-each source file.
+`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 Core_ published by the copyright holders under the LGPL 2.1 or later.
+*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
+*SPI Master Library for Arduino Zero* published by the copyright holders under
 the LGPL 2.1 or later.
 
-_Library for Arduino WiFi Shield_ published by the copyright holders under the
+*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.