How payloads work

A payload is a device that flies on an Urban Sky balloon: a camera, a sensor, a radio. This guide takes you from a device on your desk to a device that is ready to fly. Each step ends with a check that tells you it worked.

The pieces

Piece	What it is
Your payload	Your device and its software. It speaks HTTP.
Husky bus	The flight computer that carries your payload. It gives the payload power, a network (the payload LAN), and an Internet link.
Mission Control (MC)	Urban Sky's operations service. Operators see your telemetry and send your commands here.
Balto	Urban Sky's tool for buses and payloads. Its Payload Lab runs the bus's payload code on your computer, so you build without a bus.

Two ways to integrate

Path	Your payload	The bus and MC
Device API (recommended)	Serves three HTTP routes on port 8090: capabilities, telemetry, command.	The bus finds it, reads it every second, announces it to MC, and forwards MC's commands to it.
Self-announce	Announces itself to MC over HTTPS with a device token, sends telemetry, runs a command server.	MC stores the announcement and reaches your command server through the bus.

Use the device API unless your payload must talk to MC itself. It needs no device token, no Internet access from the payload, and no announcement code. The Harrier camera payload works this way.

With the device API, data moves like this:

Data	Direction	Route
Description	Payload → bus → MC	The bus reads GET :8090/api/v1/capabilities and announces your payload to MC as a child of the bus.
Telemetry	Payload → bus → MC	The bus reads GET :8090/api/v1/telemetry every second. Operators see these values.
Commands	MC → bus → payload	The bus checks each command against your capability document, then sends POST :8090/api/v1/command.
Logs and metrics	Payload → bus → Urban Sky	Plain HTTP to the bus on the payload LAN. No credentials. For your engineers and Urban Sky support.

You do not need a VPN. Older versions of this guide used a shared VPN; the bus link replaces it.

The path

Follow the steps in order. Steps 1 to 4 run on your computer with Payload Lab: no bus and no account. Steps 5 to 9 need a bus.

1. Start in Payload Lab: install Balto, try the Example sensor, point the Lab at your payload.
2. Serve the device API: capabilities, telemetry and commands on port 8090. On the self-announce path, do Connect, Report telemetry and Implement commands instead.
3. Send logs and metrics: diagnostics through the bus with PayloadTelemetry.
4. Run the Lab checks: five diagnostic checks, faults on purpose, and a diagnostic report.
5. Set up a test bench: a bus on a cable, or a cloud bench bus.
6. Video: only if your payload has a camera.
7. Test with Balto on a bus: watch your payload through Mission Control.
8. Test and troubleshoot: failures, retries, reboots.
9. Go to flight: the qualification run and the checklist before your payload flies.

Keep these open as you go: the API reference, Run on a Husky bus, and Troubleshooting.

What you build

With the device API:

Device function	Purpose	Step
Capability document	JSON description of your device, its measurements and commands.	2
Telemetry route	The current values, read by the bus every second.	2
Command route	Run a command the bus sends, and answer once per request ID.	2
Hardware adapter	Read sensors and execute commands through your driver or vendor API.	2
Logs and metrics	Send diagnostics to the bus.	3

The device API examples use acme, an air sampler. The self-announce pages use ENV-001, a sensor with a configurable sampling interval. Replace either with your device.

What you need from Urban Sky

For steps 1 to 4 (Payload Lab):

• A Balto install link, and a lab-runtime file for your computer. No account.

For steps 5 to 9 (a bus):

• An Urban Sky account for each engineer, in your organization, for operator actions in Balto.
• A test bench: a bus to plug into, or a pairing code for a cloud bench bus.
• Device API: your module name allowed on the bench bus (PAYLOAD_LAN_MODULES), so the bus forwards your commands.
• Self-announce only: a device token for your payload.
• The test API URL.

---

Next: Start in Payload Lab →