Urban Sky SDK

Appearance

AI Assistant Guide ​

Use these prompts with AI assistants like ChatGPT, Claude, or GitHub Copilot to generate simple Urban Sky SDK implementations.

JavaScript/Node.js Implementation Prompt ​

Copy and paste this prompt into your AI assistant:

Create a simple Node.js script that connects to the Urban Sky SDK and logs balloon updates.

**Requirements:**
- Load the SDK from https://sdk.atmosys.com/runtime/js/current/loader.js
- Connect and listen for balloon:update events
- Log device locations when updates are received
- Use environment variables for the API token
- Include basic error handling

**Documentation links (please review for implementation details):**
- Getting Started: https://docs.atmosys.com/guide/getting-started
- JavaScript Guide: https://docs.atmosys.com/guide/javascript-sdk
- Examples: https://docs.atmosys.com/examples/basic-usage

**Provide:**
1. Simple main script file
2. Package.json with required dependencies
3. Example .env file

Keep it simple - just enough to connect and receive data.

Python Implementation Prompt ​

Copy and paste this prompt into your AI assistant:

Create a simple Python script that connects to the Urban Sky SDK and logs balloon updates.

**Requirements:**
- Load the SDK with `exec(requests.get('https://sdk.atmosys.com/runtime/py/current/loader.py').text)` (needs `pip install requests`, and the SDK's required dependency `centrifuge-python` must be available in the environment: `pip install centrifuge-python`)
- Connect and listen for balloon:update events
- Log device locations when updates are received - the handler receives a dataclass with snake_case attributes (update.balloon_id, update.devices[i].device_id), not a dict
- Only `UrbanSkySDK.init()`, authenticate, connect, disconnect and reconnect are async - await those (including `await sdk.disconnect()`) and do not await any other SDK method
- Use environment variables for the API token
- Include basic error handling

**Documentation links (please review for implementation details):**
- Getting Started: https://docs.atmosys.com/guide/getting-started
- Python Guide: https://docs.atmosys.com/guide/python-sdk
- Examples: https://docs.atmosys.com/examples/basic-usage

**Provide:**
1. Simple main script file
2. Requirements.txt with dependencies
3. Example .env file

Keep it simple - just enough to connect and receive data.

Data Processing Prompt ​

For users who want to store and analyze balloon data:

Create a script that connects to the Urban Sky SDK and saves balloon data for analysis.

**Features needed:**
- Connect to Urban Sky telemetry feed
- Save balloon updates to JSON files
- Calculate distance between position updates
- Basic error handling and logging

**Documentation for reference:**
- Balloon Examples: https://docs.atmosys.com/examples/balloon-updates
- Error Handling: https://docs.atmosys.com/guide/error-handling

Choose JavaScript or Python and provide a simple, working solution. Focus on getting data saved first - additional features can be added later.

Web Dashboard Prompt ​

For users who want a simple web interface:

Create a basic web application that displays balloon data on a map.

**Core features:**
- Backend that connects to Urban Sky SDK
- Simple web page with a map
- Display balloon positions in real-time
- Basic error handling

**Documentation for reference:**
- SDK Guide: https://docs.atmosys.com/guide/javascript-sdk
- Examples: https://docs.atmosys.com/examples/basic-usage

Use simple technologies (Node.js + Express + Leaflet map). Focus on getting a working prototype first - advanced features can be added later.

Payload Device API Prompt ​

For a payload carried by a Husky bus:

Make my payload serve the Urban Sky payload device API on port 8090.

**Requirements:**
- GET /api/v1/capabilities returns schema_version "urbansky.payload_api.v1", modules (my module name, lower case, not gimbal/rotor/gps/camera/jetson/bus/api), identity, telemetry_fields and commands
- Every command name and telemetry key starts with "<module>." and uses lower case with _
- Every number has min and max; parameters are optional unless "required": true
- GET /api/v1/telemetry returns schema_version, hostname, generated_at and values, and answers in under a second
- POST /api/v1/command takes {command, parameters, request_id}; answer 200 {success:true,result:"queued"}, 400 for a refusal, 409 "in_progress" for a repeat still running, 503 when temporarily unable
- Remember recent request_id values and return the first answer for a repeat; never run a command twice
- Show each command's effect in telemetry
- Test it in Balto's Payload Lab: point the Lab at 127.0.0.1:8090 and get all five checks passing

**Documentation links:**
- Device API guide: https://docs.atmosys.com/guide/payload-device-api
- Payload Lab: https://docs.atmosys.com/guide/payload-lab
- Example payload: https://github.com/urban-sky/ops/tree/develop/sdk/examples/payload-device-api
- How payloads work: https://docs.atmosys.com/guide/payload-device-integration

Payload Logs and Metrics Prompt ​

For software that runs on a payload carried by a Husky bus:

Add logging and metrics to my payload software with the Urban Sky PayloadTelemetry client.

**Requirements:**
- Download urbansky_payload.py (Python) or payload-telemetry.js (Node.js) as the reference page shows, and vendor it into the project
- Create one PayloadTelemetry at startup; call close() on shutdown
- Send warn/error lines with an event name and numbers in attrs, never in the message
- Put the command request_id in attrs on every line about a command
- Report gauges with gauge() and counters with count(), using only metric names declared for the payload
- No API token: the bus identifies the payload by its LAN address

**Documentation links:**
- Python reference: https://docs.atmosys.com/api/python#payloadtelemetry-payload-logs-and-metrics
- JavaScript reference: https://docs.atmosys.com/api/javascript#payloadtelemetry-payload-logs-and-metrics
- Limits and logging rules: https://docs.atmosys.com/guide/payload-logs-metrics
- Example: https://docs.atmosys.com/examples/payload-logs-metrics

What to Expect ​

✅ You'll Get ​

  • Working code that connects and receives data
  • Simple setup with clear instructions
  • Basic error handling for common issues
  • Environment configuration for your API token

🔧 You Can Add Later ​

  • Data storage - databases, file systems, etc.
  • Advanced error handling - retry logic, monitoring
  • Data processing - analytics, alerts, calculations
  • User interface - dashboards, mobile apps

Tips for Better Results ​

Be specific about your goal:

  • "I want to log balloon positions to a file"
  • "I need to send alerts when altitude drops"
  • "I want to display data on a simple web map"

Start simple, then expand:

  • Get the basic connection working first
  • Add one feature at a time
  • Refer to our examples for additional patterns

Follow-up Prompts ​

If you want to add features to your generated code:

  • "Add file logging to save all balloon updates"
  • "Include error recovery if the connection drops"
  • "Add a simple alert when altitude goes above 30,000 feet"
  • "Save data to a database instead of console logging"

Documentation Quick Reference ​

Essential reading:

When you need more:

Testing Your Code ​

Once you have a working implementation:

  1. Test the connection - verify it connects successfully
  2. Send a test message - use our test endpoint to verify data flow
  3. Check error handling - disconnect your internet briefly to test recovery
  4. Review our examples - compare your code to our working patterns

Need help? Start simple with the basic prompts above, then add features one at a time. Contact support at support@atmosys.com if you get stuck.

Copyright © 2024 Urban Sky