UKHAS Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Payload and Flight Documents ======

The aim of this page is to reduce the confusion that appears to surround the documents required to either get your payload on the map, or to add a flight to the list of active flights.

===== What are these documents ?? =====

A payload document tells the habhub system what information your payload (balloon tracker) is sending.  If this document is missing or incorrect then your payload will not appear on the map.

A flight document is not required for the map, but has other purposes:

  - It adds your flight to the calendar so that other balloonists know when your launch is planned for
  - It adds your flight to the list of flights in dl-fldigi, making configuration a bit easier

===== What if I don't create a working payload document? =====

Your payload won't appear on the map.

===== What if I don't create a flight document? =====

Other balloonists won't be notified so you won't get much, or any, help in tracking your flight.

===== Does all this apply to APRS trackers? =====

No.  APRS trackers upload to aprs.fi, not habhub, so they don't use these documents.

====== Payload Document ======

You should create a payload document as soon as you have a working tracker, so you can test that everything is working (tracker, receiving/uploading, payload document, mapping).

Payload documents are created at http://habitat.habhub.org/genpayload/.  You can create a payload document from scratch or, if you know of a similar existing payload, you can work from a copy of that.  If you have coded your own tracker then you will of course know exactly what it is sending, so create a payload document to match. If instead you are using a commercial tracker then refer to the instructions that came with it.

With the document created, you need your tracker running **with a GPS lock** and you need to be uploading the tracker telemetry to the habhub server.  If you are using dl-fldigi (for RTTY for example) then make sure it is set to online in the menu; if you are using the LoRa Gateway then make sure that is set to online (in gateway.txt).  With these things in place then, if all is well with the payload document, your payload should appear on the map at https://tracker.habhub.org/.

If that doesn't happen, make sure that the tracker does have GPS lock, that the receiving software is reciving telemetry OK (dl-fldigi will show a lime green status box if the telemetry is OK; the LoRa gateway will display the telemetry string plus latitude/longitude/etc in the upper window), that it really is online and that it isn't displaying any error message (especially those related to online errors such as not being able to upload).  In some instances a local firewall may be blocking access to the server (this is not uncommon in schools).

The most common issue however is that the payload document is incorrect.  Take a look at the logtail - http://habitat.habhub.org/logtail/ - which will list uploaded telemetry and will show errors messages if the telemetry does not match the payload document.  Fix accordingly.

Once this is working then you can continue testing online if you wish.

One extra point - some trackers have multiple radio transmissions, each with a different payload ID.  For example the Pi In The Sky Zero kit has RTTY and LoRa transmitters, with a different payload ID for each.  In these cases, you need a separate payload document for each transmitter.
====== Flight Document ======

DO NOT create a flight document until your payload document is working (i.e. your payload is on the map); it's waste of effort which you will have to repeat should the payload document not work.

DO NOT create a flight document weeks before your flight.  It's just not possible to be confident that far out that the wind and weather will allow for a safe flight.  Generally predictions are very variable until about 3-4 days prior to the flight, so that's a good time to create the flight document.

To create a flight document, go to http://habitat.habhub.org/genpayload/ and choose the appropriate button.  Again, you can work from an existing flight document if you have one, but otherwise start from scratch.  Enter the details of the flight, and add the payload document **the one that you created earlier and have tested so you know it works**.  If you made multiple payload documents for the tracker (e.g. one for RTTY and one for LoRa) then add all payload documents to the flight document.
When you save the flight document you will be shown a document ID - copy this and save it somewhere.

Now you are ready to get the flight document approved - until then it will not get added to the calendar or the flight list in dl-fldigi.  Approval is done on the #habhub IRC channel which you can join here - https://web.libera.chat/#highaltitude.  Once joined, paste your flight document ID and a bot will display a status message, including whether you tested the payload document or not (and if you didn't, give yourself a slap for not following the instructions above!).  Of course you did follow those, so the bot will show "Tested 5 minutes ago" or similar, so you can now ask for the flight document to be approved.  If an admin is around then, assuming the flight document is in order (which essentially means that it references a payload document which you have successfully tested) then they will approve it.

If nobody replies, hang around for a while or come back later.  You can join at any time and paste your flight document ID; a bot will display a message showing if it's been approved or not.

Finally, if after approval you have to postpone or cancel the flight, you can rejoin #habhub, post the flight document ID again, and ask for it to be unapproved (so people know not to bother listening for the flight).