more progress; add rough chirpstack and mqtt instructions

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/)

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

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

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/#"
+````

doc/4-chirpstack.md

@@ -0,0 +1,69 @@
+# ChirpStack
+
+Reference install instructions: <https://www.chirpstack.io/docs/getting-started/debian-ubuntu.html>
+
+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`

doc/5-mosquitto-tls.md

@@ -0,0 +1,65 @@
+# Mosquitto TLS Setup
+
+Ref: <https://www.chirpstack.io/docs/guides/mosquitto-tls-configuration.html>
+
+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: <https://www.chirpstack.io/docs/chirpstack-gateway-bridge/configuration.html>
+
+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"
+```

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: <https://docs.heltec.org/en/node/asr650x/htcc_am02/quick_start.html#use-arduino-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.
+```