RedEdge Serial API

This document describes the protocol which can be be used by software to control the RedEdge multi-spectral camera. The camera can be controlled using serial via the host connector. For more detailed information the physical connection to the camera, see the RedEdge Integration Guide on the Downloads page of ATLAS.

Table of Contents

• RedEdge Serial API
• Table of Contents
• General Protocol Overview
  • Communicating
  • GPS
  • Commanding Captures
• Parameter Microservice
  • Supported Parameters
• Messages
  • HEARTBEAT
  • PING
  • GPS_RAW_INT
  • SYSTEM_TIME
  • ATTITUDE
  • MOUNT_STATUS
  • GLOBAL_POSITION_INT
  • GPS_STATUS
  • DIGICAM_CONFIGURE
  • DIGICAM_CONTROL
  • CAMERA_STATUS
  • CAMERA_FEEDBACK
  • PARAM_REQUEST_READ
  • PARAM_REQUEST_LIST
  • PARAM_VALUE
  • PARAM_SET

General Protocol Overview

The API is accessed via serial messages in the Mavlink format (see http://en.wikipedia.org/wiki/MAVLink and https://mavlink.io/en/about/overview.html). Mavlink provides an open data format for interaction as well as a suite of tools to assist the programmer in developing and testing the interface. RedEdge uses Mavlink v1.0 messages and communicates with the host at 57600 baud.

Communicating

The HEARTBEAT message can ensure that the RedEdge is booted and ready to receive MAVLink packets.

The PING message can be used to ensure round-trip serial connectivity with the RedEdge.

MAVLink messages include a sender System ID (sysid) parameter. The RedEdge will adopt the System ID of any message it receives, and defaults to 255 otherwise. Because of this behavior, it also ignores the Target System field, and instead assumes that any target system filtering is handled by the sender.

Many MAVLink messages include a Target Component parameter. The RedEdge will ignore any command that does not specify MAV_COMP_ID_CAMERA or MAV_COMP_ID_ALL as the Target Component.

GPS

Receipt of serial state messages will override any RedEdge internal or external sensor data, such as a connected GPS, for 5 seconds since the last state message was received. For aircraft state and mount status, messages should be sent as often as possible to ensure the latest state information is available to the camera when a capture is taken.

There are two supported ways to provide GPS data to the RedEdge. The simplest method is to send the GPS_RAW_INT message, as this single message contains both the time and position information. The other supported way is to send both SYSTEM_TIME and GLOBAL_POSITION_INT together. Sending GPS in both styles at the same time is not recommended.

Commanding Captures

The DIGICAM_CONFIGURE message can be used to set up the camera imagers

The DIGICAM_CONTROL message will command a capture, and the camera will send a CAMERA_STATUS and a CAMERA_FEEDBACK message in response

Parameter Microservice

The parameter microservice implements the MAVLink Parameter Protocol to read or change camera configuration settings.

There are 4 messages associated with the parameter microservice, which are detailed in the Messages section below: PARAM_REQUEST_READ, PARAM_REQUEST_LIST, PARAM_VALUE, PARAM_SET

The enumeration and description of each MAV_PARAM_TYPE is listed below

Supported Parameters

WARNING: The parameters below, all prefixed with a "~", are depreciated and may not be supported in future camera software versions. They are read-only, and any PARAM_SET calls will have no effect on the returned value or operation of the camera.

Messages

HEARTBEAT (0)

Versions: v1.3.2-

The RedEdge will send a heartbeat message approximately once per second using the component ID MAV_COMP_ID_CAMERA. While this message can be safely ignored, it can be used to verify the RedEdge is properly powered on.

PING (4)

Versions: v1.3.2-

Send the PING message with system_id = 0 and component_id = 0, and with a new sequence number each time, to ensure round-trip communications with the RedEdge. The PING message will be responded to with the same sequence number and the system_id and component_id of the sender (which are present in the message header).

GPS_RAW_INT (24)

Versions: v1.3.2-

Use this message to send the raw GPS information to the RedEdge as received by the host vehicle. This is the main message providing GPS information to the RedEdge. Forwarding GPS data to the camera as soon as it is received by the host will ensure the latest information is present in a new capture. Use the 64-bit time_usec field to set the camera's UTC time.

UNIX time is separate from GPS time by a fixed base epoch offset and a changing number of leap seconds (a value that most GPS receivers provide). The base offset is +315964800 seconds between UNIX time and GPS time (UNIX is referenced to 1970-Jan-1 while GPS is referenced to 1980-Jan-6).

Most GPS receivers provide a UTC time message, but it may or may not be microseconds referenced to the Unix epoch, which is what we want. However, most of them provide GPS week number (WN) plus time of week (TOW), plus number of leap seconds (LS), which makes the math easier for embedded processors.

With those GPS time inputs, UNIX epoch UTC times can be calculated by:

Base offset + (GPS Week Number * Seconds in week) + GPS Time of Week - Leap Seconds.
  315964800 + (      WN        *      604800    ) +       TOW        -      LS

As of 2019 May 05, LS equals 18.

Depending on the receiver/formatting/etc. it may be required to also add in a nanoseconds term to get sub-second resolution.

SYSTEM_TIME (2)

Versions: v1.3.2-

This message is required if using GLOBAL_POSITION_INT, as that message does not provide a UTC timestamp. It is used to update UTC time to provide accurate timestamping of images. Provide a 64-bit unix timestamp referenced to UTC time and the UNIX (not GPS) epoch. Most GPS receivers provide this information in a UTC time message.

Note: if using GPS_RAW_INT, the 64bit timestamp should be set to UTC time prior to sending.

ATTITUDE (30)

Versions: v1.3.2-

Vehicle state (roll, pitch, yaw) and vehicle rates can be provided via the ATTITUDE message. Note that this is the state of the host vehicle. The offset of the camera from the host reference frame, whether fixed or on a gimbals, should be provided via the MOUNT_STATUS message defined below.

The aircraft orientation is specified in the standard aeronautical coordinate frame, where the X axis points to the front of the vehicle, the Y axis points to the right, and the Z axis points down. Rotation order is Yaw, then Pitch, then Roll, about the Z, Y, then X axes accordingly.

MOUNT_STATUS (158)

Versions: v1.3.2-

This message can be used to provide the orientation of the camera measured by an external source by sending the MOUNT_STATUS message along with the ATTITUDE message. Anytime this value has been written in the preceding 5 seconds, it will be considered valied and will be written to image metadata.

Using these two messages, two rotations can be specified: An aircraft orientation and a camera orientation. The aircraft orientation gives the orientation of the aircraft relative to the earth frame, and the camera orientation gives the orentiation of the fixed or gimbaled camera relative to the aircraft. If the camera is fixed mounted, the camera orientation can be set to the appropriate static value and only the aircraft orientation needs to be updated.

The camera orientation represents the orientation of the camera relative to the aircraft. The default orientation, when the camera angles are all zero, is defined such that the camera is pointed straight down relative to the aircraft (aircraft nadir) with the top of the camera towards the "front" of the aircraft. The rotation order is again yaw, then pitch, then roll, about the camera Z, Y, and X axes accordingly. The camera axes are defined such that at zero rotation angle, the X axis points down (along the camera focal axis) the Z axis points towards the rear of the vehicle, and the Y axis follows right-hand rule and points out the right side of the vehicle.

The default value for these angles is zero. For a fixed camera pointed straight down relative to the aircraft, and with the top of the camera toward the front of the aircraft, this default value can be used (pitch = 0.0, roll = 0.0, yaw = 0.0).

The combination of the aircraft attitude sent in the attitude message and the rotations in the mount status message will be used to derive an earth-fixed camera orientation. It is recommended that when these messages are built on the host aircraft, the values for both the aircraft orientation and the gimbals orientation are latched into memory, then they are sent via these messages. This will ensure that the aircraft orientation and gimbals orientations were acquired at the same moment.

GLOBAL_POSITION_INT (33)

Versions: v1.3.2-

Used to update the position from a host state estimate using more than raw GPS, such as a GPS-aided INS system. This may not be the position provided by the GPS receiver, but may be more accurate and/or updated more frequently. Since this message does not have a fix status field, sending it will imply a 3D GPS fix.

GPS_STATUS (25)

Versions: v1.3.2-

GPS satellite information which is updated on the RedEdge WiFi user interface. This message is not required, but if sent the GPS status bars on the RedEdge WiFi interface will be updated.

DIGICAM_CONFIGURE (154)

Versions: v1.5.5-

NOTE: At some point, MAVLink.io decided to add a MAV_CMD_DO_DIGICAM_CONFIGURE, which, confusingly, does NOT have the same definition or 154 designation as the DIGICAM_CONFIGURE message.

Manual and Automatic mode are global switches and impact all cameras. For this reason, if commanding each imager to different manual settings, ensure that no messages are sent with auto mode enabled or all imagers will switch to auto mode.

The camera can set all of the imagers to manual mode in a single DIGICAM_CONFIGURE message by using the Extra Command value of 255. Alternatively, one DIGICAM_CONFIGURE message can be sent for each imager (numbers 0-4 for a stock camera) with an individual gain and exposure setting for each.

DIGICAM_CONTROL (155)

Versions: v1.5.5-

NOTE: At some point, MAVLink.io decided to add a MAV_CMD_DO_DIGICAM_CONTROL, which, confusingly, does NOT have the same definition or 155 designation as the DIGICAM_CONTROL message.

The DIGICAM_CONTROL message is used to command captures. Only the "Shutter Command" field is currently used, but default values are provided for the other parameters for future API compatibility.

All sensors configured to capture (e.g. via the WiFi /config route) will be captured.

CAMERA_STATUS (179)

Versions: v1.5.5-

NOTE: At some point, MAVLink.io decided to assign MAV_CMD_DO_SET_HOME to 179, conflicting with the CAMERA_STATUS message's designation. As of v6.0.0 we do not recognize the MAV_CMD_DO_SET_HOME message, and still use 179 for this message.

If a capture is commanded via MAVLink, a CAMERA_STATUS message with event type "TRIGGER" will be sent back on success

CAMERA_FEEDBACK (180)

Versions: v1.5.5-

NOTE: At some point, MAVLink.io decided to assign MAV_CMD_DO_SET_PARAMETER to 180, conflicting with the CAMERA_FEEDBACK message's designation. As of v6.0.0 we do not recognize the MAV_CMD_DO_SET_PARAMETER message, and still use 180 for this message.

If a capture is commanded via MAVLink, a CAMERA_FEEDBACK message with "Flags" type "CAMERA_FEEDBACK_CLOSEDLOOP" will be sent back on success

PARAM_REQUEST_READ (20)

Versions: v7.1.0-

Allows for reading of camera configuration settings

PARAM_REQUEST_LIST (21)

Versions: v7.1.0-

Requests that the camera send the current value for every supported parameter

PARAM_VALUE (22)

Versions: v7.1.0-

The current value of a parameter, broadcast in response to a request to get one or more parameters (PARAM_REQUEST_READ, PARAM_REQUEST_LIST) or whenever a parameter is set (PARAM_SET).

PARAM_SET (23)

Versions: v1.5.30-

Allows for configuraiton of miscellaneous settings, not already captured by another MAVLink message