Created 10 Uploading Telemetry Sondehub-Amateur Using HorusDemodLib (markdown)

10-Uploading-Telemetry-Sondehub-Amateur-Using-HorusDemodLib.md

@@ -0,0 +1,71 @@
+HorusDemodLib includes the Python reference implementation of a telemetry uploader for the 'SondeHub Amateur' [telemetry database](https://github.com/projecthorus/sondehub-infra/wiki) and [tracker](https://amateur.sondehub.org).
+
+You can use the [uploader class](https://github.com/projecthorus/horusdemodlib/blob/master/horusdemodlib/sondehubamateur.py) in your own Python code by importing it:
+
+```python
+from horusdemodlib.sondehubamateur import SondehubAmateurUploader
+```
+
+Initialise the class with:
+```
+sondehub_uploader = SondehubAmateurUploader(
+    upload_rate = 2, # Time been pushing blocks of data into Sondehub, in seconds
+    user_callsign = "Your Callsign",
+    user_position = [your_lat, your_lon], # Set both these values to 0.0 to not upload a listener position.
+    user_radio = "My radio info",
+    user_antenna = "My antenna info",
+    software_name = "horusdemodlib + your software",
+    software_version = horusdemodlib.__version__ + " your software version",
+)
+```
+
+Once initialised, listener information will be uploaded at regular intervals if a valid lat/lon is provided.
+
+To add telemetry to be uploaded, it needs to be provided as a dictionary, containing at a bare minimum these fields:
+```
+data = {
+    "callsign": "PAYLOAD_CALLSIGN",
+    "time": "2022-01-01T01:23:45Z", # Can also provide just the time part, e.g. "01:23:45Z"
+    "sequence_number": 123, # Ideally an incrementing number which is unique to each packet. Can be set to 0 without issues.
+    "latitude": -34.0,
+    "longitude": 138.0,
+    "altitude": 10000.0
+}
+```
+Other fields can be added too. The following data fields will be included for upload if available in the input dict:
+```
+temperature
+satellites
+battery_voltage
+```
+
+If you wish add further custom fields, include a dictionary entry "custom_field_names" containing a list of these fields, e.g. 
+```
+    "custom_field_names": ["internal_temperature", "pressure", "humidity"],
+    "internal_temperature": -42.0,
+    "pressure": 1000.0,
+    "humidity": 55.0
+```
+
+The following metadata fields can also be added:
+```
+snr - SNR of the received packet in dB
+f_centre - The received frequency of the packet in Hz
+modulation - The modulation type of the telemetry, e.g. 'Horus Binary v1', 'APRS', 'RTTY', 'WSPR'
+```
+
+TODOs: 
+* Clean up some of the discrepancies between the sondehub-infra field names and what this class is expecting.
+* Allow override of the uploader callsign to allow for data gathered from systems like WSPR.
+
+
+Then the data can be submitted for upload using:
+```
+sondehub_uploader.add(data)
+```
+Data may take a few seconds to be uploaded.
+
+The uploader can be stopped using:
+```
+sondehub_uploader.close()
+```