feat: add OKF knowledge bundle for hackathon challenges

Capture all six Future City Hackathon 2026 challenges as OKF v0.2 concepts, with dataset and organizer concepts, indexes, and a log.

Configure release-please with the simple strategy so the first release PR bumps the repository from 0.0.0 to 0.1.0.
This commit is contained in:
Noel Sabia committed 2026-11-13 18:23:00 +01:00
commit 7b9893a89e
45 files changed
+45531

No files matched your search

+139
View File
@@ -0,0 +1,139 @@
---
type: Dataset
title: HNVG LoRaWAN reception data
description: Real LoRaWAN uplink receptions from water meters in Heilbronn, with gateway metadata, transmitter metadata, an address table, and candidate gateway locations.
resource: ../../HNVG/transmission_data.csv
tags: [dataset, hnvg, lorawan, signal-quality, geospatial, water-meters, smart-city]
status: stable
generated: { by: opencode/deepseek-v4.1-flash, at: 2026-11-13T17:13:56Z }
sources:
- id: transmission-data
resource: ../../HNVG/transmission_data.csv
title: "transmission_data.csv — LoRaWAN uplink receptions"
- id: transmitter-meta
resource: ../../HNVG/transmitter%20meta%20data.csv
title: "transmitter meta data.csv — water meter metadata"
- id: gateway-meta
resource: ../../HNVG/gateway%20meta%20data.csv
title: "gateway meta data.csv — gateway locations"
- id: transmitter-mapping
resource: ../../HNVG/mapping%20transmitter%20id.csv
title: "mapping transmitter id.csv — device to meter mapping"
- id: hn-addresses
resource: ../../HNVG/HN_Adresses.csv
title: "HN_Adresses.csv — Heilbronn address list"
- id: potential-gw
resource: ../../HNVG/potential_gw_location.csv
title: "potential_gw_location.csv — candidate gateway sites"
- id: hnvg-readme
resource: ../../HNVG/readme%20LoRaWAN_Network_Planning_Challenge.docx
title: "LoRaWAN Network Planning Challenge — README"
author: team:hnvg
---
# Overview
This package supports the [HNVG LoRaWAN network planning challenge](/challenges/hnvg-lorawan-network-planning.md). It combines real uplink receptions from water meters with the metadata needed to join transmissions to meters and gateways, plus address and candidate-site tables for out-of-sample planning.
All transmission and metadata files use a semicolon (`;`) delimiter. Identifiers should be imported as text to preserve leading zeros.[^hnvg-readme]
# Files
| File | Rows | Contents |
|---|---:|---|
| [`transmission_data.csv`](../../HNVG/transmission_data.csv) | 8,009 | One row per received uplink message per gateway reception, with 31 columns. |
| [`transmitter meta data.csv`](../../HNVG/transmitter%20meta%20data.csv) | 593 | One row per water meter, including size, installation date, calibration year, address, and GPS coordinates. |
| [`gateway meta data.csv`](../../HNVG/gateway%20meta%20data.csv) | 8 | One row per gateway, with display name, latitude, and longitude. |
| [`mapping transmitter id.csv`](../../HNVG/mapping%20transmitter%20id.csv) | 593 | Links `device_id` and device name to `zaehlernummer_id`. |
| [`HN_Adresses.csv`](../../HNVG/HN_Adresses.csv) | 23,127 | Addresses in Heilbronn with postal code, city, and street with house number. |
| [`potential_gw_location.csv`](../../HNVG/potential_gw_location.csv) | 71 | Candidate gateway locations with an ID, latitude, and longitude. |
# Schema
## `transmission_data.csv`
31 columns, grouped by meaning. The README is the authoritative data dictionary.[^hnvg-readme]
| Group | Fields | Meaning |
|---|---|---|
| Identifiers | `id`, `device_id`, `interface_id` | Message, transmitting device, and interface identifiers. |
| Reception time | `transceived_at`, `gateways.transceived_at` | When the message was received. Timestamps are ISO 8601 in UTC (`Z`). |
| Gateway | `gateways.gateway_id`, `gateway_anzahl`, `gateway_nr` | Receiving gateway, reported gateway count, and gateway entry number within the exported message. |
| Signal quality | `gateways.rssi`, `gateways.snr` | Received signal strength (dBm) and signal-to-noise ratio (dB). |
| Radio settings | `meta.frequency`, `meta.codr`, `meta.data_rate`, `meta.datr`, `meta.region_meta.spreadingfactor`, `meta.region_meta.bandwidth` | Frequency, coding rate, data rate, spreading factor, and bandwidth. |
| Message | `meta.frame_count_up`, `meta.frame_port`, `meta.size`, `meta.lorawan_toa_ms` | Uplink frame counter, frame port, message size, and time on air. |
| Protocol flags | `meta.ack`, `meta.confirm`, `meta.adr`, `meta.adr_ack_req` | Acknowledgement, confirmation, and adaptive data rate flags. |
| Duplicated stats | `meta.gateway_stats.rssi`, `meta.gateway_stats.snr`, `meta.gateway_stats.transceived_at`, `meta.lns_packet_uuid` | Gateway statistics repeated in the export; check equivalence before dropping. |
| Other | `meta.region_meta.datarate`, `meta.stat` | Additional export metadata. |
## `transmitter meta data.csv`
`zaehlernummer_id`, `zaehlergroesse`, `einbaudatum`, `eichjahr`, `house_number`, `location`, `postal_code`, `street`, `meter_state`, `is_garden_meter`, `tags`, `latitude`, `longitude`.
Coordinates are presumably WGS 84, but the README flags uncertainty about their quality.[^hnvg-readme] This file is Latin-1 encoded in the delivered copy, not UTF-8.
## `gateway meta data.csv`
`gateways.gateway_id`, `Anzeigename`, `latitude`, `longitude`.
Coordinates use a comma as the decimal separator in the delivered file, for example `49,1254725`.
## `mapping transmitter id.csv`
`device_id`, `name`, `zaehlernummer_id`.
## `HN_Adresses.csv`
`Postleitzahl`, `Ort`, `Straße`.
## `potential_gw_location.csv`
`potential_gateway_location`, `latitude`, `longitude`.
Coordinates also use a comma as the decimal separator in the delivered file.
# Coverage snapshot
- **Transmissions:** 8,009 rows from 2026-11-04T00:01:29Z to 2026-11-10T23:59:07Z.
- **Devices observed:** 448 distinct `device_id` values. All of them appear in the 593-row device-to-meter mapping; 145 mapped meters did not transmit during the six-day window.
- **Gateways observed:** 9 distinct `gateways.gateway_id` values, while gateway metadata contains 8 rows. One observed gateway, `00007076FF03010C`, has no metadata row; the other eight observed gateways all match the metadata.
- **Signal range:** RSSI from -127 to -70 dBm; SNR from -21.5 to 12 dB.
- **Spreading factors:** 7 (3,494 rows), 8 (372), 9 (691), 10 (733), 11 (609), and 12 (2,110).
- **Metadata:** 593 meters and 593 device-to-meter mappings; 71 candidate gateway sites; 23,127 addresses.
# Data quality notes
- **Count mismatch.** The README says roughly 600 transmitters and 8 gateways. The transmission file contains 448 devices and 9 gateway IDs. Check whether the extra gateway is real, a test device, or an export artifact, and remember that not every meter necessarily transmitted during the six-day window.
- **Decimal separators differ.** `transmission_data.csv` uses a period; the coordinate columns in the metadata files use a comma. Normalise before joins or spatial calculations.
- **Encoding differs.** `transmitter meta data.csv` does not decode as UTF-8 in the delivered copy. Read it as Latin-1 or detect the encoding.
- **Packet loss is not directly observable.** Received messages alone do not establish packet-loss rates; these require a reliable estimate of expected transmissions.[^hnvg-readme]
- **Keep gateway redundancy.** The same message can be received by multiple gateways. Preserve separate gateway receptions when analysing redundancy.[^hnvg-readme]
- **GPS uncertainty.** Transmitter coordinates are of uncertain quality. Do not treat them as survey-grade.
- **Timestamp duplicates.** Several identifiers and timestamps appear in multiple fields. Check equivalence before removing duplicates.
# Example: load the transmission data
```python
import pandas as pd
df = pd.read_csv(
"HNVG/transmission_data.csv",
sep=";",
dtype=str, # preserve leading zeros in identifiers
parse_dates=["transceived_at", "gateways.transceived_at"],
)
```
For the metadata coordinates, replace the decimal comma before casting:
```python
meta = pd.read_csv("HNVG/gateway meta data.csv", sep=";", encoding="utf-8-sig")
meta["latitude"] = meta["latitude"].str.replace(",", ".", regex=False).astype(float)
meta["longitude"] = meta["longitude"].str.replace(",", ".", regex=False).astype(float)
```
# Sources
The README describes the fields, preparation, and intended use.[^hnvg-readme] All row counts and ranges above were computed from the delivered files.
[^hnvg-readme]: HNVG, "LoRaWAN Network Planning Challenge — README", challenge brief and data documentation, 2026.