fieldtracks / jellingstone

JellingStone

This repository is part of the Fieldtracks project, which aims at creating a tracking system to be used in field exercises by relief organizations.

Building

Please make yourself comfortable with ESP-IDF. JellingStone based on ESP-IDF a more-or-less standard way. It is built like other ESP-IDF Applications:

git clone https://github.com/FieldTracks/JellingStone.git

Finally run make flash to compile the project and flash it to an attached ESP32. Debug output can be watched with make monitor (or run them together with make flash monitor).

Flashing wifi and mqtt credentials to the ESP32

This will not run automatically during make flash.

1. Copy nvs_data.csv.example to nvs_data.csv
2. Edit the credentials
3. Run ./flash_nvs

Running JellingStone

The current design is designed to run on ESP32-WROOM dev-boards having a blue and a read LED. LED status indication:

• red (solely): Problems starting the APP. Jelling-Stone is not Active
• red + blue blinking
  • 1 Hz: Booting, no WLAN connection
  • 5 Hz: IP connection, no MQTT connection
  • 1 Hz / 5 Hz oscillating: Unrecoverable error occurred. Check monitor log
  • Short "twinkle": Report is submitted over MQTT
• red + blue: Device is operating (i.e. WLAN + MQTT connection, BLE is scanning and beaconing)

MQTT messages

SCAN report

Topic: JellingStone/scan/<MAC of BLE>

Header

Byte	Description
0	0x01 (Version), reserved: 0x7B for JSON Payloads
1-4	Report-ID / 32-Bit timestamp (seconds since Unix-epoch), Big-Endian / Network Byte Order
5	Message sequence number (signed), unique per report, starts at 0x01 in each report, incremented per message, a negative number marks final one, e.g. 0xFF (-1), if there's just one message
6	unsigned, number of beacon data segments in this message (report has more, if and only if there are more messages)
7 - 1100	0...255 (up to 255) segments of beacon data

Beacon Data segment

Byte	Description
0	Type and length of Beacon ID in byte. 0x14 AltBeacon 0x08 Eddystone EID 0x10 Eddystone UID 0x06 Eddystone UID, namespace matches configured one 0x01 Eddystone UID, namespace matches configured one, instance <= 255 (i.e. 1 byte) 0x02 Eddystone UID, namespace matches configured one, instance <= 65536 (i.e. 2 bytes)
1	signed, detected RSSI in dBm + 100 (i.e. -228 dBm to 27 dBm) encoded as -128 to 127
2 - 21	Beacon ID, variable length

Remarks

• Beacon data is encoded on a type-value basis, whereas the byte value of the type corresponds to the length of the ID-value
• The reporting stone (i.e. sender address) is included in the topic-name. It is part of the MQTT-header, hence.
• Using a 32-Bit timestamp is motivated by time_t having 32-Bit in ESP-IDF. Due to a year 2036-problem that may change in later versions of the protocol.

JSON status report

Topic: JellingStone/status/<MAC of BLE>

See content for details.

License

This file is part of JellingStone - (C) The Fieldtracks Project

JellingStone is distributed under the civilian open source license (COSLi).
Military usage is forbidden.

You should have received a copy of COSLi along with JellingStone.
If not, please contact [email protected]

Misc notes

• 1100 Bytes for message Tcp-header: 20 Bytes (typically), IPv: 20 / 40 Bytes, MQTT: 14-Bytes + Topic, Websocket, + TLS, should be below a minimum MTU of 1280 => Hardly any need for fragmentation

jellingstone's Issues

Testing deployment Situation

Is:
Vague ideas on the accurancy exists.

Should:
Test different parameters (beacon rate, scan interval (total / per channel). How to detect beacons reliabiy?

MQTT disconnect robustness

Ist:

• Besteht keine MQTT-Verbindung, so werden Nachrichten verworfen. Auch in ruhigen Umgebungen (z.B. Jans Arbeitszimmer) kommt es hin- und wieder zu TCP-Resets beim MQTT-Client.

Soll:

• Vorgehen entwerfen - Falls möglich, senden?
  • Nachrichten im flash Speichern (wear-out?)
  • Nachrichten im RAM speichern (Größe).

MQTT + Wifi configuration: External

Is:
All configuration data is embedded into source could

Should:

• Use NVS to externalize data
• Document how to flash with and without NVS-data

Anpassung esp-idf v4.0

Mit Version 4.0 hat sich der Syntax für die toolchain geändert. Das JellingStone-Makefile kann keine .csv-Datei mehr konvertieren.

Compression

Is: JSON-data is transmitted as is using mqtt

Should: JSON-data is optionally compressed using miniz / deflate

OTA

Is: Updates are installed using a serial cable

Should: Install Updates using a https-server

note: A http-client was recently introduced into esp-32

Erweiterung NVS config

Ist:

0. NVS funktioniert gut :-)
1. Gesetzte Optionen für JellingStone in make menuconfig (aus Kconfig.projbuild) werden nicht übernommen.
2. Weitere Settings wären gut
3. Makefile flashed die aktuelle nvs_data.csv seperat

Soll:

1. Entweder: Ausbau der Optionen aus Kconfig.projbuild - Oder: Verwendung der Optionen als Default-Werte, falls NVS-Einträge fehlen.
2. UUID, BEACON_MAJOR, BEACON_MINOR, BLE_SCAN_INTERVAL und DEVICE_COMMENT sollten auch via NVS konfigurierbar sein.
3. Der Name für die Settings sollte übergeben werden; ein gemeinsames target wäre nett, (z.B.
   make stone NVS=nvs_data.node-23, make flash_nvs NVS=nvs_data.node-23). In beiden Fällen wird die Datei nvs_data.node-23 verwendet; ersteres führt die targets flash und flash_nvs aus

Is db.c racy?

Is:

1. There's a single db_add function called on each subject discovered. If it runs an parallel, the same subject is created multiple times, eventually.

2. When detecting a subject, can looks take to long? Atm we compare up to 300 entries (uudi - memcmp, 2 integer) => a few thousend instructions

Should:

1. Here:

• Either: Running in parallel should not create equal entries
• Or: Duplicates are pruned before sending
• Or: We know, that's not running in parallel

2. Make sure, that we're fast enough

TODO: Fachlicher Service Namenslösung

Idee:

import { Injectable } from '@angular/core';
import {MqttAdapterService} from './mqtt-adapter.service';
import {Observable} from 'rxjs';
import {filter, map} from 'rxjs/operators';
import {AggregatedName} from './model/aggregated/aggregated-name';

@Injectable({
providedIn: 'root'
})
export class NamesService {

constructor(private mqtt: MqttAdapterService) { }

public name(mac: string): Observable {
return this.mqtt.aggregatedNamesSubject().pipe(filter( (map, index) => {
return map.get(mac).name;
});
}

public updateName(mac: string, name: string){
this.mqtt.publishName(mac, name);
}
}

Testing, optimizing power-consumption

Is:
The esp32 roughly consumes 100mA.

Should:
Minimize the power-consumption.
Ideally, a 2000 mAH Powerback lasts 24h. Thus 80mA would be better.

Label printing

Is:
All data describing a esp32 (mac-adresses, major, minor) is distributed via MQTT only.

Should:
All data describing a esp32 (mac-adresses, major, minor) is printing on the esp32 board using (blank, QR-Code)

BLE MAC als Topic- und Stone-Name

Ist:

• Die primäre ESP32 mac wird als topic-Name verwendet.

Soll:

• Die bluetooth mac soll als topic und stone name verwendet werden.

Feste credentials & OTA

Das flashing funktioniert recht unzuverlässig - das flash-tool ist nicht stabil.

Idee: Feste Wifi-credentials und ota verwenden? OTA dann via flashtool?

Lora + GPS

Todo: Use Lora + GPS for outdoor positioning