122 lines
4.2 KiB
Markdown
122 lines
4.2 KiB
Markdown
|
# 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.
|