From f06eaf142c68d8ce05c3bd6db6b59c5e37b842d2 Mon Sep 17 00:00:00 2001 From: Jon Roeber Date: Sat, 25 Nov 2023 00:22:12 -0500 Subject: [PATCH] more progress; add rough chirpstack and mqtt instructions --- doc/0-outline.md | 1 + doc/100-integrations.md | 21 ++++++++++++ doc/2-packet-forwarder.md | 18 +++++++++- doc/3-gateway-bridge.md | 7 +++- doc/4-chirpstack.md | 69 +++++++++++++++++++++++++++++++++++++++ doc/5-mosquitto-tls.md | 65 ++++++++++++++++++++++++++++++++++++ doc/6-device.md | 23 +++++++++++++ 7 files changed, 202 insertions(+), 2 deletions(-) create mode 100644 doc/100-integrations.md create mode 100644 doc/4-chirpstack.md create mode 100644 doc/5-mosquitto-tls.md create mode 100644 doc/6-device.md diff --git a/doc/0-outline.md b/doc/0-outline.md index 23a95ab..1733774 100644 --- a/doc/0-outline.md +++ b/doc/0-outline.md @@ -22,6 +22,7 @@ - Raspberry Pi 3 or 4 (+ power supply and MicroSD card) - Hat + Seeed WM1302 (SPI version, not USB) - Other options + - [WaveShare](https://www.waveshare.com/sx1302-868m-lorawan-gateway-b.htm?sku=22612) - Seeed SenseCAP M2 - Microtik wAP LR9 - [Rak WisGate Edge Pro](https://www.choovio.com/product/wisgate-edge-pro-rak7289cv2/) diff --git a/doc/100-integrations.md b/doc/100-integrations.md new file mode 100644 index 0000000..69ed378 --- /dev/null +++ b/doc/100-integrations.md @@ -0,0 +1,21 @@ +# ChirpStack Components and Integrations + +## "Things You Can Install" + +```mermaid +flowchart TD + subgraph Gateway + pf(Semtech Packet Forwarder) --> gb(ChirpStack Gateway Bridge) + c(ChirpStack Concentratord) --> uf(ChirpStack UDP Forwarder) + c --> mf(ChirpStack MQTT Forwarder) + uf --> gb + pf --> mf + end + mf --> mb + gb --> mb(Mosquitto MQTT Broker) + subgraph Cloud Server + mb--> cs(ChirpStack*) + end +``` + +\* Also requires PostgreSQL and Redis diff --git a/doc/2-packet-forwarder.md b/doc/2-packet-forwarder.md index 8aedc08..c13b3f3 100644 --- a/doc/2-packet-forwarder.md +++ b/doc/2-packet-forwarder.md @@ -2,6 +2,13 @@ SSH to the Raspberry Pi. +Run `raspi-config` and + +- Enable SPI +- Enable I2C +- Turn off login shell but keep serial port active +- Reboot + Clone the packet forwarder repository: `git clone https://github.com/Lora-net/sx1302_hal.git`. Go into the repo and run `make`. @@ -12,7 +19,7 @@ Make pf user + give permissions - `-m`: create home - `-s /usr/sbin/nologin`: don't allow logging in; the user's only purpose is to own the packet forwarder process - `pf`: the username -- `sudo usermod -aG gpio pf` (the `spi` group is not sufficient, and it is also not needed when part of the `gpio` group) +- `sudo usermod -aG gpio,spi,i2c,dialout pf` From the packet forwarder repo, copy files to pf user's home and set permissions: @@ -25,6 +32,15 @@ sudo chmod +x /home/pf/{lora_pkt_fwd,reset_lgw.sh} Modify the packet forward config at `/home/pf/global_conf.json.sx1250.US915`. Change `gateway_ID` to something nice (????). 8 bytes (16 uppercase hex characters) +Modify the `reset_lgw.sh` file to have the following GPIO values, [ref](https://wiki.seeedstudio.com/WM1302_module/#step4-run-semtech-sx1302-packet-forwarder): + +```sh +SX1302_RESET_PIN=17 # SX1302 reset +SX1302_POWER_EN_PIN=18 # SX1302 power enable +SX1261_RESET_PIN=5 # SX1261 reset (LBT / Spectral Scan) +AD5338R_RESET_PIN=13 # AD5338R reset (full-duplex CN490 reference design) +``` + Create SystemD unit file at `/etc/systemd/system/packet-forwarder.service`: ```systemd diff --git a/doc/3-gateway-bridge.md b/doc/3-gateway-bridge.md index f78b57f..9707619 100644 --- a/doc/3-gateway-bridge.md +++ b/doc/3-gateway-bridge.md @@ -53,4 +53,9 @@ Edit `/etc/chirpstack-gateway-bridge/chirpstack-gateway-bridge.toml` to match th upd_bind = "0.0.0.0:1730" ``` -Set up the Mosquitto integration later. +Add/change some values: + +```toml +event_topic_template="us915_1/gateway/{{ .GatewayID }}/event/{{ .EventType }}" +command_topic_template="us915_1/gateway/{{ .GatewayID }}/command/#" +```` diff --git a/doc/4-chirpstack.md b/doc/4-chirpstack.md new file mode 100644 index 0000000..1b41986 --- /dev/null +++ b/doc/4-chirpstack.md @@ -0,0 +1,69 @@ +# ChirpStack + +Reference install instructions: + +Additional instructions/tips not on the official site: + +To install the ChirpStack GPG key, use this instead of what's on the ChirpStack documentation page: + +```sh +# https://superuser.com/a/1773782 +gpg --keyserver hkps://keyserver.ubuntu.com --recv-keys 1CE2AFD36DBCCA00 && \ +gpg --export 1CE2AFD36DBCCA00 | sudo tee /etc/apt/trusted.gpg.d/chirpstack.gpg >/dev/null && \ +gpg --batch --yes --delete-keys 1CE2AFD36DBCCA00 +``` + +Don't install the `chirpstack-gateway-bridge` here; just do `chirpstack`. + +Edit `/etc/chirpstack/chirpstack.toml` as needed (specifically the PostgreSQL config). Add the missing US regions. + +## Nginx + TLS setup + +Install Lego + +Get certificate (using DNS-01 + ACME-DNS) + +Setup certificate for autorenewal and auto-reload Nginx + +Set Nginx config to have two files: + +`default`: + +```nginx +server { + listen 80 default_server; + listen [::]:80 default_server; + + server_name _; + + return 301 https://$host$request_uri; +} +``` + +`chirpstack`: + +```nginx +server { + listen 443 ssl; + listen [::]:443 ssl; + + ssl_protocols TLSv1.2 TLSv1.3; + + ssl_certificate /var/www-certs/chirpstack.roeber.dev.crt; + ssl_certificate_key /var/www-certs/chirpstack.roeber.dev.key; + + server_name chirpstack.roeber.dev; + + server_tokens off; # disable banner + + location / { + proxy_pass http://localhost:8080; + } +} +``` + +Symlink `chirpstack` to be active: `sudo ln -s /etc/nginx/sites-available/chirpstack /etc/nginx/sites-enabled/chirpstack` + +Reload Nginx: `sudo systemctl reload nginx` + +(Optional) Run [`testssl.sh`](https://github.com/drwetter/testssl.sh/) to verify security: clone, then `./testssl.sh chirpstack.roeber.dev` diff --git a/doc/5-mosquitto-tls.md b/doc/5-mosquitto-tls.md new file mode 100644 index 0000000..ca0856b --- /dev/null +++ b/doc/5-mosquitto-tls.md @@ -0,0 +1,65 @@ +# Mosquitto TLS Setup + +Ref: + +You generate a certificate authority which has the following purposes: + +- Generate a Mosquitto server certificate so gateways can connect to it via TLS +- Generate client certificates for gateways so they can prove their identity to the Mosquitto server + +When you create the CA, three files are generated: + +- `ca.csr` +- `ca.pem` +- `ca-key.pem` + +Then when you create the MQTT cert, three more files are generated: + +- `mqtt-server.csr` +- `mqtt-server.pem` +- `mqtt-server-key.pem` + +Then you add the CA (with its key) to the ChirpStack config. Make sure to change ownership to `chirpstack` when copying certs to `/etc/chirpstack/certs`. + +Then create a folder for MQTT cert and copy files. + +Set ownership and permission on the key: + +```sh +chown root:mosquitto /etc/mosquitto/certs/mqtt-server-key.pem +chmod 640 /etc/mosquitto/certs/mqtt-server-key.pem +``` + +Once set up, you can create a Gateway in ChirpStack and generate a TLS certificate. It is only shown after being created; clicking the TLS tab again later will not show the cert but will let you generate a new one. Certs don't seem to be stored anywhere. + +Don't forget to allow `8883` in the firewall. + +## Gateway Bridge Config + +Create `/etc/chirpstack-gateway-bridge/certs` folder and copy certs in. Make everything owned by `gatewaybridge`. Set permission to `640`. + +Modify the config, ref: + +Don't forget to change `tcp` to `ssl` in the server list. + +Check `journalctl` on both the bridge and Mosquitto to see that the connection is established. + +Be sure to set the Gateway ID in both the `chirpstack-gateway-bridge` and `packet-forwarder` configs (though this doesn't seem to matter? Need to experiment). Also be sure the UDP port matches between the two. + +## Troubleshooting + +Install `mosquitto-clients` on the Gateway. + +Send a message to the `test` topic: + +```sh +mosquitto_pub \ + -h chirpstack.roeber.dev \ + -p 8883 \ + --cafile /etc/chirpstack-gateway-bridge/certs/ca.crt \ + --cert /etc/chirpstack-gateway-bridge/certs/cert.crt \ + --key /etc/chirpstack-gateway-bridge/certs/cert.key \ + -t "test" \ + -d \ + -m "hello" +``` diff --git a/doc/6-device.md b/doc/6-device.md new file mode 100644 index 0000000..effdf01 --- /dev/null +++ b/doc/6-device.md @@ -0,0 +1,23 @@ +# LoRA Device Setup + +Get a CubeCell. Plug it in. + +Add yourself to the `dialout` group: `sudo usermod -aG dialout jon`. Log out and back in. + +Install the Arduino IDE v2 from Flathub: `flatpak install flathub cc.arduino.IDE2`. + +Add the Heltec Cubecell URL to the board manager: + +Install the CubeCell Development Framework in the board manager. + +Under Tools, make sure the region is set to US915. + +Pick an example sketch (CayenneLPP is fine) and enter the devEui and appKey. Both can be copied as hex array from the web UI. Upload to device. + +Frequency band settings: + +```c +uint16_t userChannelsMask[6]={ 0x00FF,0x0000,0x0000,0x0000,0x0000,0x0000 }; // US915_0 +uint16_t userChannelsMask[6]={ 0xFF00,0x0000,0x0000,0x0000,0x0000,0x0000 }; // US915_1 +uint16_t userChannelsMask[6]={ 0x0000,0x00FF,0x0000,0x0000,0x0000,0x0000 }; // US915_2, etc. +```