From b9f2ace3af3dcf31cd1aadaf1da984d599d46f35 Mon Sep 17 00:00:00 2001
From: Sebastian Hugentobler <sebastian@vanwa.ch>
Date: Tue, 24 Sep 2024 15:33:03 +0200
Subject: [PATCH] initial readme

---
 Cargo.lock |   4 +-
 README.md  | 121 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 123 insertions(+), 2 deletions(-)
 create mode 100644 README.md

diff --git a/Cargo.lock b/Cargo.lock
index 05783f7..e7f5d4f 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -517,9 +517,9 @@ checksum = "1fd0f2584146f6f2ef48085050886acf353beff7305ebd1ae69500e27c67f64b"
 
 [[package]]
 name = "bytes"
-version = "1.6.0"
+version = "1.7.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "514de17de45fdb8dc022b1a7975556c53c86f9f0aa5f534b98977b171857c2c9"
+checksum = "428d9aa8fbc0670b7b8d6030a7fadd0f86151cae55e4dbbece15f3780a3dfaf3"
 
 [[package]]
 name = "cc"
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c4b1b5a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,121 @@
+# Alert-Me
+
+[Alertswiss](https://www.alert.swiss/) is _an information hub collecting all
+relevant information pertaining to precautions and behaviour during disasters
+and emergencies in Switzerland._
+
+The usual way of getting that information (the _alerts_) is via a proprietary
+smartphone app and push notifications. While this works very well and is
+perfectly fine for most, I think that such data is a nice stepping stone to
+build upon.
+
+Fortunately, the data is not hidden and easily accessible through a JSON
+endpoint. In order to prepare this for consumption, the service in [app](./app/)
+periodically polls the JSON data and persists alerts that changed or have not
+been seen yet. Additionally it publishes all changes to an MQTT broker where
+other clients can use that data as they see fit.
+
+An example client is implemented for an
+[nRF52840](https://www.nordicsemi.com/Products/nRF52840) microcontroller in
+[display](./display/).
+
+# Workspace Organization
+
+## [app](./app/)
+
+Backend service to poll alerts and publish new ones to an MQTT broker.
+
+## [display](./display/)
+
+Microcontroller ([nRF52840](https://www.nordicsemi.com/Products/nRF52840))
+application to show basic alert information on an LCD. Because cargo has trouble
+with different target architectures (see
+[issue 9406](https://github.com/rust-lang/cargo/issues/9406)) this can not be
+part of the workspace. Go into the directory to run build commands. There is a
+separate [readme](./display/README.md) in its project directory.
+
+## [entity](./entity/)
+
+Entity definitions (_tables_) for [SeaORM](https://www.sea-ql.org/SeaORM/). This
+translates the RDBMS entities to rust structs.
+
+## [migration](./migration/)
+
+Database migrations that get run at the start of the [alert-me app](./app/).
+
+# Building
+
+The recommended way is to use [nix](https://nixos.org/download/) with
+[nix flakes](https://nixos.wiki/wiki/Flakes). It still is not for the faint of
+heart but worth the investment.
+
+Otherwise, [rustup](https://rustup.rs/) and other tools can be installed
+manually.
+
+## Nix
+
+Install [nix](https://nixos.org/download/) and enable
+[nix flakes](https://nixos.wiki/wiki/Flakes).
+
+Enter the dev environment with `nix develop`. From there on the usual rust
+commands work.
+
+To build for different architectures use `nix-build .#cross-<architecture>` with
+the desired architecture.
+
+The following architectures are supported so far (different operating systems
+would be nice but makes it more complicated):
+
+- x86_64-linux
+- i686-linux
+- aarch64-linux
+- armv6l-linux
+
+The resulting binary (statically linked with [musl](https://musl.libc.org/)) is
+written to `result/bin`.
+
+## Manual Way
+
+Install [rustup](https://rustup.rs/) and an MQTT broker (such as
+[mosquitto](https://mosquitto.org/)). When running rust commands (such as
+`cargo build`), rustup should pull in the specified toolchain. However, I can
+not test this.
+
+# Usage
+
+During development the typical way is to run `cargo run -p alert-me --`,
+followed by the cli arguments. Nothing changes if instead one runs an already
+built binary directly (such as `result/bin/alert-me`) apart from that first
+part.
+
+```
+Usage: alert-me [OPTIONS] --mqtt-broker <MQTT_BROKER> --mqtt-user <MQTT_USER> --mqtt-password <MQTT_PASSWORD>
+
+Options:
+  -i, --interval <INTERVAL>            Update interval in seconds [default: 10]
+  -c, --connection <CONNECTION>        Database connection string where timestamps are stored (SQLite, Postgres or MySql) [default: sqlite::memory:]
+  -m, --mqtt-broker <MQTT_BROKER>      MQTT broker where alerts get published
+  -p, --mqtt-port <MQTT_PORT>          MQTT port [default: 1883]
+  -u, --mqtt-user <MQTT_USER>          MQTT user
+  -P, --mqtt-password <MQTT_PASSWORD>  MQTT password
+  -h, --help                           Print help
+  -V, --version                        Print version
+```
+
+## MQTT Broker
+
+The alert-me app needs to connect to an MQTT broker to publish alerts. The
+following is an example of running your own with
+[mosquitto](https://mosquitto.org/)).
+
+Create a file `mosquitto.conf` with a content of:
+
+```
+```
+
+A password for publishing is set, so not everyone can just publish alerts. This
+is not mandatory though.
+
+Run the broker with `mosquitto -v -c mosquitto.conf`. With
+`mosquitto_sub -v -h localhost -p 1883 -t 'alerts'` new alerts will be shown as
+they arrive.