Getting started

Install api-preview

Using Fotokite Live, navigate to the System Update menu.

From the options menu, select Change Channel

Select the api-preview channel and navigate back. If api-preview does not appear for your system, contact Fotokite to get you enrolled in the Fotokite API Early Access Program (EAP).

Update the system to the latest version.

Access the API

Connect your Client Device over Wi-Fi or Ethernet. We recommend Ethernet for better reliability.

In Fotokite Live, navigate to System Connect > Advanced Settings from the options menu.

In the Upstream Ethernet section, select Bridged.

Connect your Client Device to the Ethernet port on the Ground Station and configure it to use DHCP. It will receive an IP address in the 192.168.2.0/24 range and have Internet access, as long as the Ground Station has Internet access.

Now it will be possible to access the Fotokite API over HTTP. Please ensure your request is authenticated as described in Authentication.

curl http://192.168.2.100:3128/api/v0/info/system \
--oauth2-bearer <auth_token>

If the command hangs or times out, or you receive a "no route to host" error, your Client Device is not correctly connected to the Fotokite system.

If there is a "Connection refused" error, the Fotokite system is not running an API-enabled software version. Make sure an API release is installed. Learn more in Install api-preview.

Authentication

The authentication mechanism ensures proper security and access control. Most API endpoints are protected by this workflow and are scoped, meaning each request to a protected endpoint must include a valid Bearer Token.

During the beta phase, you can use the following API Key.

DemoApiKey123

In future releases, API Keys will always be issued directly by Fotokite.

To obtain a Token, send a request using POST /v0/authentication/tokens/request by including your API Key (client_secret).

curl -X POST "http://192.168.2.100:3128/api/v0/authentication/tokens/request" \
  -H "Content-Type: application/json" \
  -d '{
    "client_secret": "DemoApiKey123"
  }'

Alternatively, you can use scopes for more granular control. Available scopes are

info, telemetry, command, media

curl -X POST "http://192.168.2.100:3128/api/v0/authentication/tokens/request" \
  -H "Content-Type: application/json" \
  -d '{
    "client_secret": "DemoApiKey123"
    "scope": "info,command"
  }'

The Token (Bearer Token) is what you use to authenticate all subsequent requests to protected endpoints.

curl -X GET "http://192.168.2.100/api/v0/info/system" \
--oauth2-bearer <auth_token>

Tokens can be invalidated via POST /v0/authentication/tokens/invalidate. Once invalidated, you must request a new one using your API Key.

Basic REST endpoints

Basic information about the system, the flight status, and current system notifications are available at these endpoints:

System: http://192.168.2.100:3128/api/v0/info/system
Flight: http://192.168.2.100:3128/api/v0/telemetry/flight
Notifications: http://192.168.2.100:3128/api/v0/telemetry/notifications

To control the system use:

These commands will start the Kite. Make sure the Sigma system is in an environment where it is safe to take off.

# Take off
curl -X POST "http://192.168.2.100:3128/api/v0/commands/flight/take_off" \
  -H "Authorization: Bearer <auth_token>"

# Set Altitude
curl -X POST "http://192.168.2.100:3128/api/v0/commands/flight/set_altitude" \
  -H "Authorization: Bearer <auth_token>" \
  -H "Content-Type: application/json" \
  -d '{"altitude":21}'

# Rotate by Angle
curl -X POST "http://192.168.2.100:3128/api/v0/commands/camera/rotate_by_angle" \
  -H "Authorization: Bearer <auth_token>" \
  -H "Content-Type: application/json" \
  -d '{ "pan": 10,  "tilt": 14}'

# Land
curl -X POST "http://192.168.2.100:3128/api/v0/commands/flight/land" \
  -H "Authorization: Bearer <auth_token>"

WebSocket subscriptions for event-based updates

The Fotokite API can notify your application about changes using a WebSocket based protocol. To demonstrate this, we will use the websocat tool; for your application, you can use any WebSocket client library.

You can subscribe to almost any endpoint by appending /subscribe to the endpoint URL:

# Flight
websocat -H="Authorization: Bearer <auth_token>" \
ws://192.168.2.100:3128/api/v0/telemetry/flight/subscribe

# Notififcations
websocat -H="Authorization: Bearer <auth_token>" \
ws://192.168.2.100:3128/api/v0/telemetry/notifications/subscribe

The Fotokite system will send updated information over the websocket as soon as it is available. The data will be formatted as a sequence of WebSocket messages, each containing one JSON object of the same form as reported by the endpoint itself.

Accessing video streams

Video streams are available as H.264 encoded RTSP sources. These can be read using any RTSP client. Learn more in Local Video Streaming (RTSP).

To retrieve information about the videostreams use:

curl -X GET "http://192.168.2.100/api/v0/info/videostreams" \
--oauth2-bearer <auth_token>

Example response.

[
  {
    "id": "Zoom",
    "protocol": "RTP",
    "frame_width": 1920,
    "frame_height": 1080,
    "codec": "H.264",
    "url": "rtsp://192.168.2.100:5010/video"
  },
  {
    "id": "Wide",
    "protocol": "RTP",
    "frame_width": 1920,
    "frame_height": 1080,
    "codec": "H.264",
    "url": "rtsp://192.168.2.100:5014/video"
  },
  {
    "id": "Thermal",
    "protocol": "RTP",
    "frame_width": 320,
    "frame_height": 240,
    "codec": "H.264",
    "url": "rtsp://192.168.2.100:5012/video"
  }
]

The video streams will only be available while the Kite is flying; otherwise the cameras turn off after a while. For low latency, we recommend using GStreamer with a pipeline set up like this:

// GStreamer
gst-launch-1.0 rtspsrc location=rtsp://192.168.2.100:5010/video drop-on-latency=true latency=300 ! rtph264depay ! h264parse ! avdec_h264 ! queue ! xvimagesink

Some code examples can be found here

PreviousEarly Access Program

NextCode Examples

Last updated 1 year ago