Krautspace/doorstatus
3
0
Fork 1
Code Issues 2 Pull requests Projects Releases Packages Wiki Activity
doorstatus/README.md
Philipp Matthias Schaefer 001c7cd568 Implement and document Arduino software
2020-12-28 21:56:24 +01:00

5.4 KiB
Raw Blame History

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

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 or the provided Makefile to verify or flash the sketch.

For the Makefile to work, Arduino CLI 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 and Arduino CLI 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 and Arduino CLI 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 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.