forked from Krautspace/doorstatus
146 lines
5.4 KiB
Markdown
146 lines
5.4 KiB
Markdown
# 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.
|
|
|
|
|
|
|
|
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.
|