add systemd and improve env.template

README.md

@@ -1,25 +1,67 @@
 # LocationHub
 
-TODO
+Selfhosted backend for LoRaWAN based Location Tracker that support multiple location providers like GNSS, Gateway-Triangulation, WiFi-Triangulation and BLE-Triangulation. 
+We suggest to use [The Things Network](https://www.thethingsnetwork.org/) (TTN) as middleware for relaying the LoRaWAN payload.
 
 ## Setup
 ### Prerequisites
 - Node.js >= 22.11.0
 - Maria DB >= 11.6.2
+- Webserver like nginx
 
 ### Database
 **Change name of database and credentials as you like!**
-
 - Create new database: `CREATE DATABASE dev_locationhub;`
 - Create new user for database: `GRANT ALL PRIVILEGES ON dev_locationhub.* TO 'dbuser'@'localhost' IDENTIFIED BY '1234';`
 - Import tables: `/usr/bin/mariadb -u dbuser -p1234 dev_locationhub < server/sql/tables.sql`
 
+### Configuration
+- Copy the `.env.template` to `.env` and configure as you like.
+- Use a strong token/secret for the webhook.
+- Add your [Wigle](http://wigle.net) API token to translate MAC addresses to coordinates
+- Use [systemd](server/scripts/locationhub.service) to start the server.
+
 ### TTN Integration
-Create new Webhook for application. Set base url and enable "Uplink message" to api `/api/ttn/webhook`.
+Create new Webhook for your application. Set base url to `https://your.domain.tld` and enable "Uplink message" to api `/api/ttn/webhook`.
 Add a addidtional header: 
 - Type: `authorization` 
-- Value: `Bearer your-very-secure-token`
+- Value: `Bearer your-very-secure-token-from-the-env-file`
 
+## Add a Location Tracker
+We use the [SenseCAP T1000-B](https://www.seeedstudio.com/SenseCAP-Card-Tracker-T1000-B-p-5698.html) from seeedstudio because of the fair price and multiple location providers. You can use any LoRaWAN enabled tracker that is able to communicate with TTN and supports the needed fields in the payload data.
+
+### Onboard SenseCAP T1000-B
+1. Download and install the App [SenseCraft](https://play.google.com/store/apps/details?id=cc.seeed.sensecapmate) 
+2. Skip the user account at startup with `Skip` in the upper right corner
+3. Select the `Tracker T1000`
+4. Connect to your SenseCAP T1000-B
+5. In the `Settings` tab select `The Things Network` as Platform under `LoRa`
+6. Copy `Device EUI`, `AppEUI` and `AppKey`
+7. Save LoRa settings
+8. Under `Geolocation` select Geolocation Strategy as `Bluetooth+Wi-Fi+GNSS`
+9. Set `GNSS Max Scan Time (s)` to 120
+10. Save Geolocation settings
+11. Exit App with return arrow to trigger re-init of SenseCAP T1000-B
+
+### Register SenseCAP T1000-B
+1. Open your Application in TTN and navigate to `End devices`
+2. Click `Register end device` in the upper right corner
+3. Set input method to `Enter end device specifics manually`
+ - Frequency plan: `Europe 863-870 MHz (SF9 for RX2 - recommended)`
+ - LoRaWAN version: `LoRaWAN Specification 1.0.4`
+ - Regional Parameters version: `RP002 Regional Parameters 1.0.3`
+4. Place as `JoinEUI` the `AppEUI`
+5. Place the `DevEUI`
+6. Place the `AppKey`
+7. Set a name for end device
+8. Click `Register end device`
+9. Check if new end device joins the TTN
+10. Place the [Uplink Payload Formatter](TTN/sensecap_payload_formater.js) as `Custom Javascript formatter` for new end device
+
+## Testing
 ### Testing Webhook
-- To test the webhook use the python script `ttn-webhook-dummy.py` to send prerecorded TTN Uplinks.
+- To test the webhook use the python script [ttn-webhook-dummy.py](server/scripts/ttn-webhook-dummy.py) to send prerecorded TTN Uplinks.
 - To test the script you can use `while true; do echo -e "HTTP/1.1 200 OK\r\nContent-Type: text/plain\r\n\r\nSuccess"; nc -l -p 8080 -q 1; done`
+
+### Emulating Wigle API
+- To emulate the Wigle API use the python script [wigle-dummy.py](server/scripts/wigle-dummy.py) to translate MAC addresses to coordinates. 

server/.env.template

@@ -1,10 +1,18 @@
+# Database 
 DB_NAME=""
 DB_USER=""
 DB_PASSWORD=""
-DB_HOST=""
+DB_HOST="localhost"
-DB_DIALECT=""
+DB_DIALECT="mariadb"
-DB_PORT=""
+DB_PORT="3306"
+
+# Server
+PORT="3000" #Port the server runs on, match with your reverse proxy config
+
+# TTN Webhook
 WEBHOOK_TOKEN="" #Token that is placed a the TTN Webhook auth
+
+# Wigle API
 WIGLE_TOKEN="" # Go to account and generate token "Encoded for use"
 WIGLE_BASE_URL="https://api.wigle.net"
 WIGLE_NETWORK_SEARCH="/api/v2/network/search"

server/scripts/locationhub.service

@@ -0,0 +1,22 @@
+[Unit]
+Description=LocationHub
+After=network.target systemd-networkd-wait-online.service mysqld.service
+
+[Service]
+Type=simple
+User=locationhub
+WorkingDirectory=/home/locationhub/git/LocationHub/server/
+ExecStart=/usr/bin/npm run dev
+Restart=on-failure
+StandardOutput=append:/var/log/LocationHub.log
+StandardError=append:/var/log/LocationHub.log
+
+[Install]
+WantedBy=multi-user.target
+```
+Activate Systemd Job
+```
+systemctl daemon-reload
+systemctl enable locationhub.service
+systemctl start locationhub.service
+systemctl status locationhub.service