From 66358d36513ae3bc52cda76826f8ed51221e6caf Mon Sep 17 00:00:00 2001
From: Thanasi Pantazides <thanasipantazides@gmail.com>
Date: Thu, 5 Dec 2024 12:47:49 -0600
Subject: [PATCH] adding documentation of formatter.service systemd unit file

---
 PISETUP.md             | 50 ++++++++++++++++++++++++++++++++++++++++++
 README.md              |  2 ++
 util/formatter.service | 17 ++++++++++++++
 3 files changed, 69 insertions(+)
 create mode 100644 util/formatter.service

diff --git a/PISETUP.md b/PISETUP.md
index 764b5a3..4bba5e2 100644
--- a/PISETUP.md
+++ b/PISETUP.md
@@ -109,3 +109,53 @@ $ sudo apt-get install googletest
 The recent v1.83.* versions of `boost` are not yet (as of March 2024) available in the Debian distribution, so I specify an earlier version for the Raspberry Pi install.
 
 Once complete, you may need to modify the [CMakeLists.txt](CMakeLists.txt) to point `NLOHMANNJSON_ROOT` to the correct directory. The path you input should contain the file `json.hpp`.
+
+## Setting up `systemd` for run on boot
+The `formatter` software is supposed to run after the Raspberry Pi boots for flight operation. This behavior is enabled by [`systemd`](https://systemd.io/), which runs daemons (background processes) in Linux. We interface with `systemd` using the `systemctl` command line tool. 
+
+### Provide a `formatter.service` configuration
+If you are setting up a Pi from scratch, copy the file [`foxsi-4matter/util/formatter.service`](util/formatter.service) into the directory `/etc/systemd/system/` on the Raspberry Pi. This file is known as a `systemd` "unit," and does the following:
+1. Requires network and users to be set up by the boot process before starting.
+2. Uses the working directory `/home/foxsi/foxsi-4matter` for running commands.
+3. Runs this command in that working directory:
+```bash
+nohup bin/formatter --verbose --config foxsi4-commands/systems.json
+```
+4. If the process fails, waits 10 seconds before trying to start it again.
+5. Always tries to restart the process when it fails.
+
+Unit files like this are used broadly in Linux, and you will find plenty of resources if you search the internet.
+
+### Start the service
+Once you have put a valid `formatter.service` unit file in `/etc/systemd/system` on the Pi, register this new service with `systemctl`:
+```bash
+sudo systemctl daemon-reload
+```
+
+Enable the service to start on boot:
+```bash
+sudo systemctl enable formatter.service
+```
+
+Start running the service (or just reboot the Pi):
+```bash
+sudo systemctl start formatter.service
+```
+
+You can query the status of the service, and see recent `stdout` from it, with
+```bash
+sudo systemctl status formatter.service
+```
+
+You can also stop running, and disable automatically running the service on boot (respectively) with the following commands:
+```bash
+sudo systemctl stop formatter.service		# stop the current running formatter
+sudo systemctl disable formatter.service 	# stop from running formatter on boot
+```
+When you modifiy `formatter` software, if you want your new binary to be run on boot, make sure you put it in the same place so that `systemctl` can find it: `/home/foxsi/foxsi-4matter/bin/formatterr`. Or you will need to modify `/etc/systemd/system/formatter.service` to set a new working directory containing your binary.
+
+>[!NOTE]
+> On macOS, I am unable to open `.service` files from the Finder (I get errors that ".service files are not supported on Mac"). I can open these files using the Terminal, however. For example, to open in TextEdit, do:
+> ```bash
+> open -a TextEdit formatter.service
+> ```
\ No newline at end of file
diff --git a/README.md b/README.md
index 9c8b635..872c41a 100644
--- a/README.md
+++ b/README.md
@@ -217,6 +217,8 @@ sudo systemctl disable formatter.service
 sudo systemctl enable formatter.service        
 ```
 
+If you need to set up `formatter.service` from scratch to run on boot, see [PISETUP.md](PISETUP.md). If you need to find and modify the `formatter.service` unit file, it is in `/etc/systemd/system/` on the FOXSI-4 flight Pi. 
+
 When the service is running, if you need to debug you will need to find the correct `~/foxsi-4matter/log/` file to collect evidence. This can be inconvenient to track down since Unixtime changes with every reboot. 
 
 A helpful debugging workflow is to stop the Formatter service, then launch it manually so you can see the stdout output:
diff --git a/util/formatter.service b/util/formatter.service
new file mode 100644
index 0000000..b881635
--- /dev/null
+++ b/util/formatter.service
@@ -0,0 +1,17 @@
+[Unit]
+Description=Begin running formatter on boot.
+After=multi-user.target
+Requires=network.target
+
+[Service]
+Type=idle
+User=foxsi
+WorkingDirectory=/home/foxsi/foxsi-4matter
+Environment="ARG1=--verbose" "ARG2=--config" "ARG3=foxsi4-commands/systems.json"
+ExecStartPre=/bin/sleep 10
+ExecStart=nohup bin/formatter $ARG1 $ARG2 $ARG3 &
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target