# 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. [Prometheus Metrics](#prometheus-metrics)
4. [Add a Location Tracker](#add-a-location-tracker)
    - [Onboard SenseCAP T1000-B](#onboard-sensecap-t1000-b)
    - [Register SenseCAP T1000-B](#register-sensecap-t1000-b)
5. [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`

### Prometheus Metrics
Use `https://your.domain.tld/api/metrics` to retrieve useful insides for monitoring.

## 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! 🎉