From d9f21662594081262b797f3904381e193b5485aa Mon Sep 17 00:00:00 2001
From: Gregor Riepl <onitake@gmail.com>
Date: Sun, 31 Jan 2021 16:56:47 +0100
Subject: [PATCH] Document usage of control server and added example systemd
 unit

---
 README.md               | 49 ++++++++++++++++++++++++++++++++++++-----
 uncanny/uncanny.service | 11 +++++++++
 2 files changed, 55 insertions(+), 5 deletions(-)
 create mode 100644 uncanny/uncanny.service

diff --git a/README.md b/README.md
index 97fc18a..1d9d0eb 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,7 @@ All hardware and software was designed by members of
 diagrams, printed circuit board layouts and source code for anyone to use and
 modify. Refer to the LICENSE file for details.
 
-The name "Matemat" is a portmanteau of "mate" (as in mate tea) and "automat"
+The name "Matemat" is a portmanteau of "mate" (as in [yerba mate](https://en.wikipedia.org/wiki/Mate_%28drink%29) and "automat"
 (the German word for vending machine). The device is mainly intended to dispense
 mate tea based soft drinks, but may be used for other types of beverages too.
 
@@ -66,10 +66,11 @@ End switch feedback interface.
 
 Senses the status of the end switches and sends CAN bus messages on changes.
 
-This module requires firmware. Connect an Atmel programmer to the ISP header,
-change into the firmware directory `feedback/firmware/` and run:
+This module requires firmware. Connect an Atmel programmer to the ISP header
+of the feedback board, make sure the programming jumper is shorted and run:
 
 ```shell
+cd feedback/firmware/
 make flash
 ```
 
@@ -77,10 +78,11 @@ make flash
 
 Interface between CAN bus and power board.
 
-This module requires firmware. Connect an Atmel programmer to the ISP header,
-change into the firmware directory `poweriface/firmware/` and run:
+This module requires firmware. Connect an Atmel programmer to the ISP header
+of the poweriface board, make sure the programming jumper is shorted and run:
 
 ```shell
+cd poweriface/firmware/
 make flash
 ```
 
@@ -92,6 +94,43 @@ Environment sensor interface.
 
 Wring schema of the old vending machine.
 
+### uncanny
+
+Central controller software. Has a simple HTTP API for controlling output and
+checking the current fill status of each slot.
+
+Written in Go, must be compiled before use:
+
+```shell
+cd uncanny/
+go build ./cmd/uncanny
+```
+
+The resulting `uncanny` executable should be running on the controlling
+Raspberry Pi. An example SystemD unit is provided in `server/uncanny.service`.
+Copy `uncanny` to `/usr/bin`, install the service file to
+`/lib/systemd/system/uncanny.service` and enable it with:
+
+```shell
+cd uncanny/
+cp uncanny /usr/bin/
+cp uncanny.service /lib/systemd/system/
+systemctl daemon-reload
+systemctl enable uncanny.service
+```
+
+A working CAN bus is required to run `uncanny`. You need to make sure the bus
+is initialized at boot. On RaspberryOS/Raspbian/Debian, this can be achieved
+with the following lines in `/etc/network/interfaces`:
+
+```
+auto can0
+iface can0 inet manual
+    pre-up /sbin/ip link set $IFACE type can bitrate 125000 loopback off sample-point 0.75
+    up /sbin/ip link set $IFACE up
+    down /sbin/ip link set $IFACE down
+```
+
 ## Bus
 
 ### Topology
diff --git a/uncanny/uncanny.service b/uncanny/uncanny.service
new file mode 100644
index 0000000..d505e5b
--- /dev/null
+++ b/uncanny/uncanny.service
@@ -0,0 +1,11 @@
+[Unit]
+Description=Matemat control server
+Requires=network.target
+After=network.target
+
+[Service]
+Type=simple
+ExecStart=/usr/bin/uncanny
+
+[Install]
+WantedBy=multi-user.target