92 lines
4.0 KiB
Markdown
92 lines
4.0 KiB
Markdown
# LocationHub
|
|
|
|
**Self-hosted backend for LoRaWAN-based location tracking, supporting multiple location providers such as GNSS, Gateway-Triangulation, WiFi-Triangulation, and BLE-Triangulation.**
|
|
We recommend using [The Things Network](https://www.thethingsnetwork.org/) (TTN) as middleware for relaying LoRaWAN payloads.
|
|
|
|
---
|
|
|
|
## Table of Contents
|
|
1. [Setup](#setup)
|
|
- [Prerequisites](#prerequisites)
|
|
- [Database](#database)
|
|
- [Configuration](#configuration)
|
|
2. [TTN Integration](#ttn-integration)
|
|
3. [Add a Location Tracker](#add-a-location-tracker)
|
|
- [Onboard SenseCAP T1000-B](#onboard-sensecap-t1000-b)
|
|
- [Register SenseCAP T1000-B](#register-sensecap-t1000-b)
|
|
4. [Testing](#testing)
|
|
- [Testing Webhook](#testing-webhook)
|
|
- [Emulating Wigle API](#emulating-wigle-api)
|
|
|
|
---
|
|
|
|
## Setup
|
|
|
|
### Prerequisites
|
|
Ensure the following dependencies are installed:
|
|
- **Node.js** >= 22.11.0
|
|
- **MariaDB** >= 11.6.2
|
|
- A web server, such as **nginx**
|
|
|
|
---
|
|
|
|
### Database
|
|
**Customize the database name and credentials to your preference.**
|
|
Follow these steps to set up the database:
|
|
- 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 file and rename it to .env:
|
|
- 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 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-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. However, you can use any LoRaWAN-enabled tracker that is compatible with TTN and supports the required payload fields.
|
|
|
|
### 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 `GNSS+Wi-Fi`
|
|
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](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.
|
|
|
|
|
|
Happy tracking! 🎉 |