RedEdge HTTP Control 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 HTTP via either the ethernet connector or the 802.11 WIFI access point. For more detailed information on connecting to the camera, see the RedEdge Users's Guide.

Table of Contents

General Protocol Overview

The API is accessed via HTTP connection to port 80 at the camera IP address. All data is exchanged in the JSON format.

The actual value of the IP address depends on the configuration. When accessing the camera via its WIFI access point, the camera IP address will be 192.168.10.254. When the camera is connected to an Ethernet network, the camera IP address will be 192.168.1.83 by default.

NOTE: Future software updates may allow the camera to support assignment of IP addresses via DHCP, and may support a broadcast-based device discovery protocol for locating cameras on a network.

Routes

Command Capture [/capture]

Versions: v1.3.2-

URL: /capture

Supported verbs: GET, POST

The camera can be commanded to take a capture by either a GET or POST request to this URL. Both actions have the same effect. The command can take several arguments, provided as parameters in the URL or as a JSON body.

When using the preview option, the a new JPEG preview image will be generated based on the preview_band option in the configuration settings. This preview is the image displayed on the web server user interface.

The cache_jpg and cache_raw parameters allow the user to create and cache images in camera RAM, for temporary access without impacting SD card data throughput. The images saved to the SD card for any given capture are still controlled by the main configuration settings. This allows, for example, a user to cache jpegs from two bands to be retrieved quickly during flight, while still saving RAW images to the SD card for later retrieval. Note that cached image files are only available temporarily. Cached files are kept only for the last two capture commands which had non-zero cache_raw or cache_jpeg arguments, so it is important if you are downloading these cached files that you finish downloading the file before issuing more than one subsequent capture command (only captures with caching enabled count here).

Command Arguments

Argument Type Default Description Versions
anti_sat bool false If true, strong anti-saturation rules are used for the capture v1.3.2-
block bool false When 'true', the HTTP request will not return until the capture is complete. v1.3.2-
detect_panel bool false When 'true', the camera will not return an image until a MicaSense reflectance panel is detected. Also see /detect_panel v5.0.0-
preview bool false When 'true', updates the current preview image. v1.3.2-
cache_jpeg int /config's enabled_bands_jpeg Bitmask for bands from which to capture and cache JPEG images. See note below. v1.3.2-
cache_raw int /config's enabled_bands_raw Bitmask for bands from which to capture and cache RAW (tiff) images. See note below. v1.3.2-
store_capture bool true Store this image to the SD card based on configuration settings.
(JPEG and/or RAW may be stored depending on configuration)
v1.3.2-
use_post_capture_state bool false When 'true', the camera will try and retrieve state information from the /capture_state route before falling back on default values. v6.0.0-

NOTE: For bit masks, bit 0 corresponds to imager #1, bit 1 to imager #2, and so forth. As an example, to capture all five bands, the bit mask value should be 31 (in binary: 11111). To capture only band #4, the value should be 8 (01000).

Response Properties

The response will always be a JSON object, however the contents of the JSON object can vary depending on the provided arguments.

Property Type Description Versions
status string One of 'pending', 'complete', 'error' v1.3.2-
id string ID representing this capture. Save this to retrieve the status of a capture later. v1.3.2-
time
( optional)
string ISO8601 datetime string providing the UTC time of actual image capture. This property is only present if the block argument is true v1.3.2-
jpeg_cache_path
(optional)
object An object containing a property for each band for which JPEG cacheing was enabled. (e.g. '1', '2', ...). The value of each property is the path to retrieve the cached JPEG file for that band. This property is only present if cache_jpg was non-zero and the block arguments was true v1.3.2-
raw_cache_path
(optional)
object Like jpeg_cache_path, but for cached raw images v1.3.2-

If the block argument is false, then the status property in the response will always be 'pending' or 'error'. When block is set to true, then the status property will be either 'complete' or 'error'.

Note that blocking calls return as soon as the capture is complete, and the cached files are available for download. The files may not have been transferred to the SD card storage yet. You may use the /capture/:id route to lookup results for a previous capture (including the location of SD card files after they are saved).

Example Request:
GET /capture?preview=true captures an image, generating a preview JPEG and saving RAW files to the SD card

Example Response to GET /capture?store_capture=true&cache_jpeg=19&cache_raw=31&block=true:

JPEG and TIFF files are commanded to be cached for bands 1, 2, and 5. The store_capture parameter was true, so the actual raw bands that are stored to the card depends on the current configuration settings. The response shown below assumes that all 5 bands are set to save on capture

{
   "id": "kE5pogpXYEIrhI4aIxX2",
   "jpeg_cache_path": {
      "1": "/images/tmp31.jpg",
      "2": "/images/tmp32.jpg",
      "5": "/images/tmp33.jpg"
   },
   "raw_cache_path": {
      "1": "/images/tmp26.tif",
      "2": "/images/tmp27.tif",
      "3": "/images/tmp28.tif",
      "4": "/images/tmp29.tif",
      "5": "/images/tmp30.tif"
   },
   "status": "complete",
   "time": "2016-01-28T02:28:30.000Z"
}

The following response can be expected when block is 'false', because the capture has not been completed when the object is returned.

{
   "status" : "pending",
   "id' : "i89jfi73irj49f74"
}

Capture Status Request [/capture/:id]

Versions: v1.3.2-

URL: /capture/:id

Supported verbs: GET

This route can be called to poll the status of a previously commanded capture. Only those paths that are valid for the capture will be shown. For example, if no cached files were requested for this capture, then the jpeg_cache_path and raw_cache_path fields will not be present.

Example URL:
/capture/i89jfi73irj49f74

Example Responses:

{
   "status" : "complete",
   "id" : "i89jfi73irj49f74",
   "time" : "2014-10-08T20:27:16.321Z",
   "jpeg_cache_path" : {
      "1" : "/images/i89jfi73irj49f74_1.jpg",
      "2" : "/images/i89jfi73irj49f74_2.jpg",
      "5" : "/images/i89jfi73irj49f74_5.jpg"
   },
   "raw_cache_path" : {
      "1" : "/images/i89jfi73irj49f74_1.tif",
      "2" : "/images/i89jfi73irj49f74_2.tif",
      "5" : "/images/i89jfi73irj49f74_5.tif"
   },
   "jpeg_storage_path" : {
      "1" : "/files/0021SET/000/IMG_0000_1.jpg",
      "2" : "/files/0021SET/000/IMG_0000_2.jpg",
      "3" : "/files/0021SET/000/IMG_0000_3.jpg",
      "4" : "/files/0021SET/000/IMG_0000_4.jpg"
   },
   "raw_storage_path" : {
      "1" : "/files/0021SET/000/IMG_0000_1.tif",
      "2" : "/files/0021SET/000/IMG_0000_2.tif",
      "3" : "/files/0021SET/000/IMG_0000_3.tif",
      "4" : "/files/0021SET/000/IMG_0000_4.tif"
   }
}

KMZ Captures [/captures.kmz]

Versions: v1.5.10-

URL: /captures.kmz

Supported verbs: GET

/captures.kmz will return a kmz file with the contents of all captures currently on the SD card. This is especially useful when flying multiple flights across one or more areas to ensure continuous coverage across those areas.

Note: The KML file provided by the /captures.kml route is still accessable by downloading the KMZ, and extracting the kml file from it.

Example KML File

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
   <Document>
      <Folder>
         <name>"0000SET"</name>
         <Placemark>
            <name>710</name>
            <Point>
               <coordinates>-110.7228486,32.902748314,37.2748314</coordinates>
            </Point>
         </Placemark>
         <Placemark>
            <name>711</name>
            <Point>
               <coordinates>-110.72628388,32.902745594,37.2745594</coordinates>
            </Point>
         </Placemark>
      </Folder>
   </Document>
</kml>

Camera Exposure [/exposure]

Versions: v1.3.2-

URL: /exposure

Supported verbs: GET, POST

The camera exposure object controls the camera's exposure mode, and sets manual exposure values. Manual exposure values are only used when the enable_man_exposure field in the config object is set to true. The exposure settings are not persistent and the camera will revert to the default behavior of automatic exposure control when it is powered off.

Note: Automatic exposure mode is recommended during normal operation. The camera has automatic gain and exposure control (AGC) rules which are designed for aerial data collection. The AGC rules will prevent blurring in most cases by first increasing imager gain, and will prevent over-exposure of bright subjects.

The exposure properties are expressed in miliseconds. The gain properties must be integers with a value of 1, 2, 4 or 8.

Property Type Default Description Versions
enable_man_exposure bool (none) When 'true', the camera will use the manually set exposure and gain values, rather than performing AGC. v1.3.2-
exposure[1-5] float (none) Exposure (in ms) for sensor [1-5] v1.3.2-
gain[1-5] int (none) Gain for sensor [1-5]. Allowed values: [1,2,4,8] v1.3.2-

Example object:

{
   "enable_man_exposure" : false
   "exposure1" : 0.06,
   "exposure2" : 1.0,
   "exposure3" : 8.0,
   "exposure4" : 25.0,
   "exposure5" : 0.5,
   "gain1" : 1,
   "gain2" : 2,
   "gain3" : 4,
   "gain4" : 8,
   "gain5" : 1,
}

Detect Panel Control [/detect_panel]

Versions: v5.0.0-

URL: /detect_panel

Supported verbs: GET, POST

This route reports the current state of the panel detection algorithm. You can also send it an abort command, in which case any currently running panel detection will complete its capture regardless of whether a panel was successfully found

Property Type Default Description
abort_detect_panel bool false When 'true', any actively running panel detection captures will be forced to complete.
detect_panel bool (none) When 'true', a panel detection capture is active

Example POST to cancel a panel detection capture:

{
   "abort_detect_panel" : true
}

Example response to the POST example above:

{
   "detect_panel" : false
}

Camera Position [/gps]

Versions: v1.3.2-

URL: /gps

Supported verbs: GET, POST

This command can be used to retrieve the active location, velocity, and time, or to provide these values to the camera.

This command can be used in lieu of an external GPS attached to the camera to provide the camera with a position (for example, from the aircraft GPS). Anytime this value has been written in the last 5 seconds, it will take priority over a camera attached GPS and will be used instead of the attached GPS when writing image metadata.

See /capture_state for an additional option for injecting image metadata.

Property Type Default Description Versions
latitude float NaN The camera latitude in radians v1.3.2-
longitude float NaN The camera longitude in radians v1.3.2-
altitude float NaN The camera altitude above datum ellipsoid in meters v1.3.2-
vel_n float NaN The camera northing velocity in m/s v1.3.2-
vel_e float NaN The camera easting velocity in m/s v1.3.2-
vel_d float NaN The camera descent rate in m/s v1.3.2-
p_acc float (none) Camera positional accuracy in meters, one sigma v1.3.2-
v_acc float (none) Camera vertical accuracy in meters, one sigma v1.3.2-
fix3d bool (none) True if there is a valid 3D fix v1.3.2-
utc_time string (none) ISO8601 datetime string UTC time string v1.3.2-

Example Message:

{
   "latitude" : 0.1363053,
   "longitude" : -2.399923234,
   "altitude" : 332.503,
   "vel_n" : 0.73,
   "vel_e" : 1.2,
   "vel_d" : 0.49,
   "p_acc" : 2.456,
   "v_acc" : 1.54,
   "fix3d" : true,
   "utc_time" : "2014-10-08T20:27:23.321Z"
}

Camera Orientation [/orientation]

Versions: v1.3.2-

URL: /orientation

Supported verbs: GET, POST

This command retrieves or sets the current camera orientation.

This command can be used to provide the orientation of the camera measured by an external source by POST'ing the orientation angles. Anytime this value has been written in the preceding 5 seconds, it will be considered valid and will be written to image metadata.

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 orientation of the fixed or gimbaled camera relative to the aircraft. If desired, the aircraft orientation can be set to zero, and in the case the camera orientation becomes relative to the earth. Alternatively, if the camera is fixed mounted, the camera orientation can be set to the appropriate static value and only the aircraft orientation is updated.

The aircraft orientation is specified in the standard aeronautical coordinate frame, where the Z-axis points down, the Y-axis points to the right, and X-axis points to the front of the vehicle. The default orientation, when the vehicle angles are all zero, is defined such that the Z-axis points directly towards the center of the earth, and the X-axis points towards true north. Rotations about the Z, Y, and X axes correspond to the angles psi, theta, and phi, respectively. For the vehicle, this means that psi corresponds to yaw, theta corresponds to pitch, and phi corresponds to roll. Rotation order is about the Z, Y, then X axis, or yaw, then pitch, then roll.

The camera orientation represents the orientation of the camera relative to the aircraft. The axes used are referenced to the camera, not the vehicle. The camera’s Z-axis points towards the bottom of the camera, the Y-axis points to the right of the camera, and the X-axis points in the direction the camera is facing, along the camera focal axis. The default orientation, when the camera angles are all zero, is defined such that the camera’s Z-axis is aligned with the aircraft’s negative X-axis, the camera’s Y-axis is aligned with the aircraft’s Y-axis, and the camera’s X-axis is aligned with the aircraft’s Z-axis. This corresponds to the camera looking at nadir, with the top of the camera pointing towards the front of the vehicle. Rotations about the Z, Y, and X axes of the camera correspond to the angles psi, theta, and phi, respectively. For the camera, this means that psi corresponds to pan, theta corresponds to tilt, and phi corresponds to roll. The rotation order is about the Z, Y, then X axis, or pan, then tilt, then roll.

For a fixed camera pointed straight down relative to the aircraft, and with the top of the camera toward the front of the aircraft, the value of 0 can be used for all angles.

POST properties

Property Type Default Description Versions
aircraft_phi float (none) radians v1.3.2-
aircraft_theta float (none) radians v1.3.2-
aircraft_psi float (none) radians v1.3.2-
camera_phi float (none) radians v1.3.2-
camera_theta float (none) radians v1.3.2-
camera_psi float (none) radians v1.3.2-

Example POST message:

{
   "aircraft_phi" : -0.1512,
   "aircraft_theta" : 0.1363053,
   "aircraft_psi" : -0.399923234,
   "camera_phi" : 0.0,
   "camera_theta" : 0.0,
   "camera_psi" : 0.0
}

State at Capture Time [/capture_state]

Versions: v6.0.0-

URL: /capture_state

Supported verbs: POST

If the 'use_post_capture_state' argument is set to 'true' when a /capture command is made, then sending POST data to this route within 1 second of the top of frame will result in the provided data being written to the image metadata, instead of any other potential sources of these data, such as a directly connected GPS.

Data provided to this route is accepted in logical groups, where all parameters in the group must be present, or else all parameters in that group will be ignored, and any valid value the camera has from other sources will be used instead. For instance, providing a latitude and logitude, but no altitude will result in all of those parameters being collectively ignored, and the image will instead get a latitude, longitude, and altitude from an alternate data source.

The groups are as follows:

  • aircraft_attitude: aircraft_phi, aircraft_theta, aircraft_psi
  • camera_attitude: camera_phi, camera_theta, camera_psi
  • gps: latitude, longitude, altitude
  • accuracy: p_acc, v_acc
  • utc_time: utc_time

The response to a successful POST is a list of these groups, and whether they were 'set' or 'ignored' by the POST

If a POST is sent outside of the window for acceptance, or two POSTs are sent for a single capture, a 409 status is returned, indicating a conflict between the POST supplied data and what was actually written to the file metadata, along with an error string indicating why the data were rejected.

POST properties

Property Type Default Description
aircraft_phi float (none) radians
aircraft_theta float (none) radians
aircraft_psi float (none) radians
camera_phi float (none) radians
camera_theta float (none) radians
camera_psi float (none) radians
latitude float (none) The camera latitude in radians
longitude float (none) The camera longitude in radians
altitude float (none) The camera altitude above datum ellipsoid in meters
p_acc float (none) Camera positional accuracy in meters, one sigma
v_acc float (none) Camera vertical accuracy in meters, one sigma
utc_time string (none) ISO8601 datetime string UTC time string

Example POST message:

{
   "aircraft_psi" : 0,
   "utc_time" : "2019-05-01T01:02:03.456Z",
   "latitude" : 1.23456,
   "longitude" : -0.987654,
   "altitude" : 31.4159
}

Example response to above POST message:

{
  "accuracy": "ignored",
  "aircraft_attitude": "ignored",
  "camera_attitude": "ignored",
  "gps": "set",
  "utc_time": "set"
}

Example response to a POST message sent outside of the timing window allowed:

Response status: 409

{
  "error": "Data received too late for capture. Ignoring."
}

Config [/config]

Versions: v1.3.2-

URL: /config/

Supported verbs: GET, POST

The config object contains camera configuration options. These options are persistent between camera power cycles, except where exceptions are noted.

Update (POST) requests may provide any subset of the config properties as parameters and only those properties that are provided will be modified.

Object properties:

Property Type Default Description Versions
streaming_enable boolean (none) Enable continuous rapid capture of JPEG previews.
This setting is NOT persistent across power cycles.
v1.3.2-
streaming_allowed boolean (none) When 'false', prevents streaming_enable from working v3.2.0-
preview_band string (none) Selects band(s) to be rendered in preview JPEG
Allowable values: "band1", "band2", "band3", "band4", "band5", "band6"*, "multi"
* "band6" is only valid for cameras with 6 or more bands
This setting is NOT persistent across power cycles.
v1.3.2-
operating_alt integer (none) Aircraft operating altitude above ground (meters) v1.3.2-
overlap_along_track integer (none) Desired along track overlap percentage (0-100) v1.3.2-
overlap_cross_track integer (none) Desired cross track overlap percentage (0-100) v1.3.2-
auto_cap_mode string (none) Auto capture mode. Allowable values: "disabled", "overlap", "timer", "ext" v1.3.2-
timer_period float (none) Period between timer captures (seconds) v1.3.2-
ext_trigger_mode string (none) Allowable values: "rising", "falling", "longpwm", "shortpwm" v1.3.2-
pwm_trigger_threshold float (none) The long/short pulse width threshold for PWM input, in milliseconds v1.3.2-
enabled_bands_raw integer (none) Bit mask of bands that are enabled for raw capture storage v1.3.2-
enabled_bands_jpeg integer (none) Bit mask of bands enabled for jpeg capture and storage v1.3.2-
enable_man_exposure boolean (none) When true, the user-provided exposure settings are used instead of the automatic exposure control. This field is not persistent. v1.3.2-
gain_exposure_crossover float (none) Exposure time (in seconds) at which the gain should be increased in order to properly expose rather than increasing the exposure time further. v1.5.0-
ip_address string (none) Sets the Ethernet IP address of the camera. Must be a valid IP address, e.g. "123.456.789.012". v1.5.0-
raw_format string (none) Selects what raw output format the camera saves as. Allowable values: "TIFF", "DNG". v1.5.0-
network_mode string (none) Selects whether the camera will act as a main camera or auxiliary camera in a MicaSense network. Allowable values: "main", "auxiliary".
Changed from "master/slave" to "main/auxiliary" in v7.0.0
v1.5.0-
ext_trigger_out_enable bool (none) When 'true', top of frame pulses will be generated on a camera-specific pin.
Note that activating this feature may cause damage to the camera if the pin is also driven by an external device.
See pin_modes for new method of enabling top of frame output
v1.5.20-v5.1.12
ext_trigger_out_pulse_high bool (none) When 'true', top of frame pulses will be generated by resting low, with the rising edge of the pulse indicating the top of frame of a capture. Otherwise, the top of frame pulse will be generated by resting high, with the falling edge of the pulse indicating the top of frame of a capture. v1.5.20-
agc_minimum_mean double (none) Sets the minimum normalized mean value for each image during Automatic Gain Control (AGC).
Valid values are from 0.0 to 1.0, inclusive.
Changed from volatile to persistent in v4.2.2
v4.1.0-
audio_enable bool (none) When 'true', the camera is allowed to produce sounds. Note that not all camera models have a method of producing sound, in which case this field is not a functional parameter. v5.0.0-
audio_select_bitfield unsigned int (none) Bitfield that masks individual audio features. Setting a bit to 0 will disable the individual associated audio feature.
Bit Feature
0 Tone when a normal capture is taken (anti_sat=false)
1 Tone when a panel capture is taken (anti_sat=true)
2 Tone when a panel detection is active
v5.0.0-
pin_modes object (none) Sets the mode of configurable pins on the camera. The object should contain integer-named fields, with integer values matching the desired function enumeration.
Note that setting a pin as an output may cause damage to the camera if the pin is also driven by an external device.
See /pin_mux for details on the enumeration and pins.
v6.0.0-
injected_gps_delay double (none) Sets the fixed expected delay in seconds between the timestamp contained in the GPS source (whether that be from a directly connected GPS, DLS, or injected via one of the APIs), and the time the message is received.
Also see /timesources.
v6.0.0-

Example JSON Data for POST: Providing the following JSON object as the body of a POST to /config will update the 'streaming_enable', 'timer_period', and 'pin_mode' options, while leaving all other options unchanged.

{
   "streaming_enable" : false,
   "timer_period" : 1.0,
   "pin_modes" : {
      "0" : 0
   }
}

Pin Configuration Options [/pin_mux]

Versions: v6.0.0-

URL: /pin_mux

Supported Verbs: GET

This read-only object returns information regarding configurable pins and their available functions.

See pin_modes in the /config route for details on how to use these values

Property Type Description
functions object Each element of the functions object is named numerically, and is a FunctionEnumeration Object. See details below.
pins array of PinEnumeration Objects Describes the pin for each index. See details on the PinEnumeration object below.

FunctionEnumeration Object Details

Property Type Description
id int The integer enumeration that this function is represented by.
name string A human-readable string describing the function performed when this enumeration is selected.

PinEnumeration Object Details

Property Type Description
name string A human readable string indicating what physical pin is configured by this index.
opts array of integers Lists which functions the pin is capable of performing. Uses the same enumeration as the FunctionEnumeration id field.

Example GET Response:

{
   "functions" : {
      "0" : {
         "id" : 0,
         "name" : "Disabled"
      },
      "1" : {
         "id" : 1,
         "name" : "PPS Input"
      },
      "128" : {
         "id" : 128,
         "name" : "PPS Output"
      },
      "129" : {
         "id" : 129,
         "name" : "Top of Frame Output"
      },
      "2" : {
         "id" : 2,
         "name" : "External Trigger Input"
      }
   },
   "pins" : [
      {
         "name" : "Pwr/Trg Pin 1",
         "opts" : [0,1,2,128,129]
      },
      {
         "name" : "GPS Pin 4",
         "opts" : [0,1,2,128,129]
      },
      {
         "name" : "GPS Pin 5",
         "opts" : [0,1,2,128,129]
      }
   ]
}

Status [/status]

Versions: v1.3.2-

URL: /status

Supported Verbs: GET

This read-only object returns the current camera status information.

Property Type Description Versions
sd_gb_free float The amount of free space on the SD card (GB) v1.3.2-
sd_gb_total float The total amount of storage on the SD card (GB) v1.3.2-
sd_gb_type string The filesystem type of the SD card. One of 'FAT32', 'exFat', or 'Unknown' v7.0.0-
sd_warn bool When true, indicates the low SD space warning threshold is met or using unsupported SD filesystem type v1.3.2-
sd_status string Status of the SD card, one of 'Ok', 'NotPresent', or 'Full' v1.3.2-
bus_volts float The measured supply voltage v1.3.2-
gps_used_sats int The number of satellites used by GPS fix v1.3.2-
gps_vis_sats int The number of visible GPS satellites v1.3.2-
gps_warn bool True when the GPS receiver reports interference detected v1.3.2-
gps_lat float The current latitude (radians) v1.3.2-
gps_lon float The current longitude (radians) v1.3.2-
course float The direction of travel in NED v1.3.2-
alt_agl float Altitude above ground level v1.3.2-
alt_msl float Altitude above mean sea level v1.3.2-
p_acc float Positional accuracy of GPS fix v1.3.2-
utc_time datetime Format YYYY-MM-DDTHH:MM:SS.SSS v1.3.2-
vel_2d float Horizontal velocity (m/s) v1.3.2-
sv_info array Array of svinfo objects (see below) v1.3.2-
auto_cap_active bool True indicates that the camera's automatic capture mode is activated v1.3.2-
dls_status string The DLS state. One of 'Ok', 'NotPresent', 'Programming', 'Initializing'*, or 'Error'*
* This state was added in v6.0.0
v1.5.27-
gps_time datetime Format YYYY-MM-DDTHH:MM:SS.SSS v1.5.27-
utc_time_valid bool When 'true', the utc_time provided in this status is believed to be correct v1.5.27-
time_source string What type of time source is being used by the camera. One of 'GPS', 'PPS', or 'None' v6.0.0-

SVINFO Sub-object

Property Type Description
azimuth float Satellite azimuth (deg)
elevation float Satellite elevation (deg)
channel int Receiver channel
cno int Satellite carrier-to-noise ratio
used_flag bool Satellite is being used in the position fix
diff_flag bool Satellite is using differential corrections
orbit_info bool Receiver has some orbital infomation about this satellite
orbit_is_eph bool Orbital information is ephemeris data
sv_healthy bool This satellite is healthy and can be used for positioning
svid int Space Vehicle ID
quality int Quality indicator for this satellite

Example GET response:

{
   "alt_agl": 14.798,
   "alt_msl": 283.55,
   "auto_cap_active": false,
   "bus_volts": 4.695,
   "course": 169.4142636445688,
   "gps_lat": 36.2709446,
   "gps_lon": -104.7104612,
   "gps_time": "2014-11-13T18:34:12.345Z",
   "gps_used_sats": 5,
   "gps_vis_sats": 16,
   "gps_warn": false,
   "p_acc": 5.820000171661377,
   "sd_gb_free": 20.0958251953125,
   "sd_gb_total": 29.70469665527344,
   "sd_warn": false,
   "sd_status": "Ok",
   "sv_info": [
      {
         "azimuth": 0.8203047513961792,
         "channel": 9,
         "cno": 41,
         "diff_flag": false,
         "elevation": 0.6108652353286743,
         "orbit_info": true,
         "orbit_is_eph": true,
         "quality": 7,
         "sv_healthy": false,
         "svid": 5,
         "used_flag": false
      },
      {
         "azimuth": 0,
         "channel": 14,
         "cno": 15,
         "diff_flag": false,
         "elevation": -1.588249564170837,
         "orbit_info": false,
         "orbit_is_eph": false,
         "quality": 3,
         "sv_healthy": false,
         "svid": 8,
         "used_flag": false
      },
      ...
   ],
   "time_source": "GPS",
   "utc_time": "2014-11-13T18:34:0.000Z",
   "utc_time_valid": true,
   "vel_2d": 0.08,
}

Network Status [/networkstatus]

Versions: v1.5.3-

URL: /networkstatus

Supported Verbs: GET

The network status API provides information about the MicaSense network, including all RedEdge cameras and DLS's. The devices are presented as an array called "network_map".

Properties

Property Type Description Version
bands array A list of the center wavelengths of the sensors on the device, in nanometers (nm). v1.5.3-
bandwidths array A list of the bandwidths of the sensors on the device, in nanometers (nm). v7.0.0-
device_type string The type of device. Will report as either "Camera", "DLS", or "DLS 2". v1.5.3-
gps_source string Indicates where the device is receiving GPS information from. Will report as either an empty string, "direct", or "host". v1.5.3-
mode string Indicates which network mode the device is operating in. v1.5.3-
sd_gb_free float Space remaining (in GB) on storage device. v7.0.0-
sd_gb_total float Total size (in GB) of storage device. v7.0.0-
sd_status string Status of the storage device, one of 'Ok', 'NotPresent', or 'Full' v7.0.0-
sd_type string The filesystem type of the storage device. One of 'FAT32', 'exFat', or 'Unknown' v7.0.0-
sd_warn bool When true, indicates the low storage device space warning threshold is met or using unsuppored storage device filesystem type v7.0.0-
serial string Reports the serial number of the device. v1.5.3-
sw_version string Reports the software version currently running on the device. v1.5.3-

Example Reponse to GET /networkstatus:

{
   "network_map" : 
      [
         {  "bands":[475,560,668,840,717],
            "bandwidths":[20,20,10,40,10],
            "device_type":"Camera",
            "gps_source":"",
            "mode":"main",
            "sd_gb_free":25.33200073242188,
            "sd_gb_total":29.70773315429688,
            "sd_status":"Ok",
            "sd_type":"FAT32",
            "sd_warn":false,
            "serial":"RM02-1839163-SC",
            "sw_version":"v7.0.0"
         },
         {  "bands":[475,560,668,840,717],
            "bandwidths":[20,20,10,40,10],
            "device_type":"Camera",
            "gps_source":"",
            "mode":"auxiliary",
            "sd_gb_free":25.63470458984375,
            "sd_gb_total":29.70469665527344,
            "sd_status":"Ok",
            "sd_type":"FAT32",
            "sd_warn":false,
            "serial":"RM02-1839202-SC",
            "sw_version":"v7.0.0"
         },
         {
            "bands":[450,500,550,570,600,610,650,680,730,760,810,860],
            "bandwidths":[],
            "device_type":"DLS 2",
            "gps_source":"direct",
            "mode":"auxiliary",
            "serial":"DA03-1921711-OB",
            "sw_version":"v1.2.3"
         }
   ]
}

Time Sources Information [/timesources]

Versions: v6.0.0-

URL: /timesources

Supported Verbs: GET

This read-only object contains information about what time source the camera is using, and provides an estimated delay value between the various time sources and the time used by the camera.

Property Type Description
time_sources array of TimeSource objects Contains an unordered array of TimeSource objects
TimeSource Object Definition
Property Type Description
active bool When 'true', the camera is actively using this time source to estimate time
delay double The estimated delay between the camera's time and the sources' reported time, in seconds.
If no estimate is known, 1.797693134862316e+308 will be returned
type string The type of the time source. Either 'GPS' or 'PPS'

Example GET response:

{
   "time_sources" : [
      {
         "active" : false,
         "delay" : -0.108506053686142,
         "type" : "GPS"
      },
      {
         "active" : true,
         "delay" : 5.09058661890549e-09,
         "type" : "PPS"
      }
   ]
}

Version Information [/version]

Versions: v1.3.2-

URL: /version

Supported Verbs: GET

This read-only object contains the software version and the device serial number.

Property Type Description
sw_version string The version of software installed on the camera
serial string The camera serial number

Example response:

{
    "sw_version" : "v1.2.3",
    "serial" : "1220001"
}

File Access [/files/*]

Versions: v1.3.2-

URL: /files/path/on/sd/card

Supported verbs: GET

The file access API provides a method to get the contents of the SD card currently inserted in the camera. GET can return one of three alternatives:

  1. If the provided path describes a regular file, the file is returned.
  2. If the provided path describes a directory, a json object is returned that provides a directory listing as an array of descriptors for sub-directories and files at that path.
  3. If the provided path does not exist, a 404 with JSON error message is returned

Example URLs:
GET /files/
GET /files/000SET/
GET /files/001SET/000/IMG_1234_1.tif

Example Response to GET /files/:

{
   "files": []
   "directories": ["0000SET", "0001SET", "0002SET"]
}

Example Response to GET /files/000SET:

{
   "files": [
      { "name": "paramlog.dat", "size": 3219234 }
   ],
   "directories": ["000"]
}

Example Response to GET /files/000SET/000:

{
   "files": [
      { "name": "IMG_0000_1.tif", "size": 5000000 },
      { "name": "IMG_0000_2.tif", "size": 5000000 },
      { "name": "IMG_0000_3.tif", "size": 5000000 },
      { "name": "IMG_0000_4.tif", "size": 5000000 },
      { "name": "IMG_0000_5.tif", "size": 5000000 }
   ],
   "directories": []
}

File Deletion [/deletefile/*]

Versions: v1.3.2-

URL: /deletefile/path/on/sd/card

Supported verbs: GET

The delete file API provides a method to delete files on the SD card currently inserted in the camera. GET can return one of three alternatives:

  1. If the provided path describes a regular file, the file is deleted
  2. If the provided path describes a directory that is empty, the directory is deleted
  3. If the provided path does not exist, or the path is a directory that is not empty, a 503 code is returned with a JSON message stating the error

Example URLs:
GET /deletefile/
GET /deletefile/0000SET/000
GET /deletefile/0001SET/000/IMG_1234_1.tif

Example Response to GET /deletefile/0000SET/000/IMG_0000_1.tif:

{
   "message" : "Deleted file: 0000SET/000/IMG_0000_1.tif"
}

Example Response to GET /deletefile/0000SET/000:

{
   "message" : "Deleted directory: 0000SET/000"
}

Example Response to GET /deletefile/non/existant/path/file.txt:

{
    "message": "Could not delete file: non/existant/path/file.txt"
}

Example Response to GET /deletefile/0000SET:

{
    "message": "Directory 0000SET is not empty"
}

Wifi Configuration [/wifi]

Versions: v1.3.2-

URL: /wifi

Supported verbs: GET, POST

NOTE: Disabling wifi from the wifi interface may not return a response. WiFi will be re-enabled when the camera is power-cycled

Properties

Property Type Description
enable bool Set to 'false' to disable wifi for this session

Example Response:

{
    "wifi_enabled" : false
}

Reformat SD Card [/reformatsdcard]

Versions: v1.5.9-

URL: /reformatsdcard

Supported verbs: POST

This route allows you to completely erase everything on the SD card at once. All images will be deleted, along with any other files you may have on your SD card at the time of the command.

You cannot undo the card wipe performed by this command.

Properties

Property Type Description
erase_all_data bool Set to 'true' to reformat the SD card

Example Response to POST {"erase_all_data":true}:

{
    "message": "Sucessfully reformatted",
    "reformat_status": "success"
}

Camera Information [/camera_info]

Versions: v1.3.2-

URL: /camera_info

Supported verbs: GET

This endpoint provides information physical information about the camera, including nominal lens parameters and information about the nominal filters installed for each band.

Example URL: GET /camera_info

Example Response to GET /camera_info:

{
   "1" : {
      "type" : "bandpass",
      "center_nm": 498.2,
      "bandwidth_nm": 12,
      "focal_lenth_px" : 1100.0,
      "image_width": 1280,
      "image_height": 960
   },
   "2" : {
      "type" : "bandpass",
      "center_nm": 620.3,
      "bandwidth_nm": 10,
      "focal_length_px": 1100.0,
      "image_width": 1280,
      "image_height": 960
   },
   ...
}

Distortion Calibration [/calibration/distortion]

Versions: v1.3.2-

URL: /calibration/distortion

Supported verbs: GET

Used to retrieve the lens distortion calibration parameters for all five cameras. See the "RedEdge File Format ICD" document for more information regarding the lens calibration parameters.

Properties

Property Type Description
k array Array of three lens radial coefficients [k1, k2, k3]
p array Array of two tangential coefficients [p1,p2]
fx float Effective lens focal length in the x direction in pixels
fy float Effective lens focal length in the y direction in pixels
cx float Lens center x position in pixels
cy float Lens center y position in pixels

Example data

{
   "1": {
      'k' : [1.23e-1, 4.56e-2, 6.78e-3],
      'p' : [1.23e-1, 4.56e-2],
      'fx' : 1100.2,
      'fy' : 1101.7,
      'cx' : 623.76,
      'cy' : 473.54
   },
   "2": {
      'k' : [1.23e-1, 4.56e-2, 6.78e-3],
      'p' : [1.23e-1, 4.56e-2],
      'fx' : 1100.2,
      'fy' : 1101.7,
      'cx' : 623.76,
      'cy' : 473.54
   },
   "3": {
      ...
   },
   "4": {
      ...
   },
   "5": {
      ...
   }
}

Vignette Calibration [/calibration/vignette]

Versions: v1.3.2-

URL: /calibration/vignette

Supported verbs: GET

Used to retrieve the lens vignette calibration parameters. One set of parameters is returned for each of the five cameras.

Properties

Property Type Description
k array Array of vignette calibration coefficients [k0,k1,k2,k3,k4,k5]
cx float Vignette center x position in pixels
cy float Vignette center y position in pixels

Example URLs:
GET /calibration/vignette

Example data

{
   "1" : {
      'k': [1.2e-1, 2.1e-2, 5.1e-2, 5.1e-3, 5.1e-4, 5.1e-5],
      'cx': 623.19,
      'cy': 495.24
   },
   "2" : {
      'k': [1.2e-1, 2.1e-2, 5.1e-2, 5.1e-3, 5.1e-4, 5.1e-5],
      'cx': 621.21,
      'cy': 477.90
   },
   "3": {
      ...
   },
   "4": {
      ...
   },
   "5": {
      ...
   }
}

Rig Relatives Calibration [/calibration/rig_relatives]

Versions: v4.1.0-

URL: /calibration/rig_relatives

Supported verbs: GET

Used to retrieve the relative rotations between lenses. Calibration is returned as an array for each band, where the first element of the array is the X-rotation, the second is the Y-rotation, and the third is the Z-rotation, all in radians. Rotations should be applied to the image first as Z, then Y, then X. In matrix form, it should look like v_cal = Rx*Ry*Rz*v . When you rotate all images from a capture by their respective rotation values, they should all align, assuming the target is effectively at infinity. See our Image Processing Tutorial for more details on using these values.

Example URLs:
GET /calibration/rig_relatives

Example data

{
   "1" : [-0.0025194,-0.00756218,-0.000187806],
   "2" : [0,0,0],
   "3" : [-0.00126232,0.00104639,-0.00439204],
   "4" : [-0.0068887,-0.00415932,0.000341805],
   "5" : [-0.00455459,-0.00342963,-0.002376]
}

Prepare for Power Down [/powerdownready]

Versions: v7.0.0-

URL: /powerdownready

Supported verbs: GET, POST

This route reports the readiness of the camera for power down. It can also be used to request the camera to prepare for power down.

NOTE: This route will not actually power down the camera. It places the camera in a "safe" state for power down, meaning that the storage media is unmounted after ensuring that any pending data has been written out. This prevents the possiblility of the storage media becoming corrupted. This is an alternative to holding the button of the camera down for five seconds.

Property Type Description
ready_for_power_down bool When reporting 'true', camera is ready to be powered down
power_down bool When requested 'true', camera will prepare to power down

Example URL:
GET /powerdownready

Example Response:

{
   "ready_for_power_down" : false
}

Example POST data to request power down preparation

{
   "power_down" : true
}

Thermal NUC [/thermal_nuc]

Versions: v7.0.0-

URL: /thermal_nuc

Supported verbs: GET, POST

This route returns information regarding temperature change in Kelvin and number of seconds since the last non-uniform calibration (NUC) of the thermal imager.

NOTE: This route only works with cameras that have a thermal imager, such as the Altum.

If the property "nuc_now" is present in the POST request and set to true then this route commands the camera to NUC the thermal imager. If a NUC is commanded then auto-NUCing will be disabled. Auto-NUCing cannot be re-enabled unless the camera is rebooted, so regular commands must be sent to this route in order to maintain high quality thermal data. We have found that NUCing once every five minutes or a change of 2 Kelvin maintains good thermal image quality.

Property Type Description
nuc_now bool Post true to NUC
elapsed_seconds_since_nuc int Number of seconds since last nuc
delta_deg_K_since_nuc float Change in temperature (measured in K) since the last nuc
message string Notification in case of NUC failure or NUC already in progress

Example URL:
GET /thermal_nuc

Example Response:

{
   "delta_deg_K_since_nuc":301.5400085449219,
   "elapsed_seconds_since_nuc":249.52
}

Example POST data for NUC request

{
   "nuc_now" : true
}

Deprecated or Removed Routes

KML Captures [/captures.kml] - REMOVED

Versions: v1.3.2-v1.5.9

URL: /captures.kml

Supported verbs: GET

Use the /capture.kmz route instead

/captures.kml will return a kmz file with the contents of all captures currently on the SD card. This is especially useful when flying multiple flights across one or more areas to ensure continuous coverage across those areas.

Example KML File

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
   <Document>
      <Folder>
         <name>"0000SET"</name>
         <Placemark>
            <name>710</name>
            <Point>
               <coordinates>-110.7228486,32.902748314,37.2748314</coordinates>
            </Point>
         </Placemark>
         <Placemark>
            <name>711</name>
            <Point>
               <coordinates>-110.72628388,32.902745594,37.2745594</coordinates>
            </Point>
         </Placemark>
      </Folder>
   </Document>
</kml>