Mirrors/OpenSolo
1
0
Fork 0
mirror of https://github.com/OpenSolo/OpenSolo.git synced 2025-04-29 22:24:32 +02:00
Code Issues Packages Projects Releases Wiki Activity
OpenSolo/shotmanager/docs/App-ShotManager communication.md

51 KiB
Raw Permalink Blame History

App-ShotManager Communication

This document details App-Sololink communication for use in the Sololink behaviors.

Setup

ShotManager is the process that runs on Sololink that handles behaviors.

App-ShotManager communication happens over TCP on port 5507.

Shot Flows

Multipoint cable cam

The Multipoint Cable Cam shot allows the copter to fly a Path described by a spline.

There are two modes: Record and Play

  • In Record mode, ShotManager collects and assembles Keypoints into a Path.
  • In Play mode, ShotManager controls the copter to fly along the Path defined in Record mode.
Record Mode

  • When ShotManager enters Record mode, it clears the existing Path (if there is one) and starts a new one.

  • ShotManager attempts to create a new Keypoint when:

  • After creating a Keypoint, ShotManager sends SOLO_SPLINE_POINT to the app.

  • It's possible for Keypoint creation to fail.

  • ShotManager can coalesce multiple recording requests into a smaller number of Keypoints (i.e. to remove duplicates); however, it must respond with exactly one SOLO_SPLINE_POINT message for each SOLO_SPLINE_POINT or SOLO_MESSAGE_RECORD_POSITION message it receives from the app. This is to provide an ACK mechanism.

Play Mode

  • ShotManager enters Play mode:

    • In response to an Artooo button press.
    • When it receives a SOLO_SPLINE_PLAY message from the app.

  • ShotManager will only enter Play mode after a valid Path has been constructed in Record mode.

  • When ShotManager enters Play mode, it sends all Keypoints on the current Path to the app using SOLO_SPLINE_POINT messages

  • The vehicle doesn't fly or snap to the path until it receives a message from the app

  • The app sends a SOLO_SPLINE_ATTACH message to tell ShotManager to fly to the Path and await further commands.

  • Once attached, the app uses the SOLO_SPLINE_SEEK message to tell ShotManager to fly the path.

  • As the vehicle is flying, ShotManager sends SOLO_SPLINE_PLAYBACK_STATUS messages to the allow the app to visualize Solo’s location on the flight path.

Definition of a Path

  • A Path is an ordered collection of Keypoints.

  • Path indices are unique.

  • Valid Keypoints are constructed only by ShotManager; the validity of Keypoints must be confirmed by ShotManager if created or re-loaded by the app.

  • A Path is valid if and only if:

    • It contains at least two Keypoints.
    • All its Keypoints are valid.
    • The indices of its Keypoints form a complete set; that is, a path with n Keypoints contains a Keypoint with each of the indices 0..n-1.

  • Index 0 is the beginning of the Path. Index n is the end of the Path.

  • When Path positions are expressed parametrically, index 0 corresponds to a parametric value of 0.0; index n corresponds to a parametric value of 1.0.

Path Equivalence -- TBD

Camera Direction -- TBD

The direction in which the camera points with respect to the Path is ShotManager implementation-specific. Eventually, this API will provide options to control this; it is currently undefined.

Selfie

Selfie is much simpler than cable cam.

The flow must be initiated by the app via a SOLO_MESSAGE_SET_CURRENT_SHOT. ShotManager then expects 3 locations sent using SOLO_MESSAGE_LOCATION. They are:

  • 1st selfie waypoint (near point)
  • 2nd selfie waypoint (far point)
  • Selfie ROI point

Upon receiving these 3 points, ShotManager will put Solo into guided mode and the selfie will automatically start. It’s controllable and pausable just like cable cam though.

Locations cannot be changed after they are received. Instead, stop and start a new selfie.

User can press ‘FLY’ to exit as in cable cam.

Orbit

Either the app can request that orbit starts (via SOLO_MESSAGE_SET_CURRENT_SHOT) or the user can initiate from Artoo, in which case ShotManager will tell the app via a SOLO_MESSAGE_GET_CURRENT_SHOT. This only works if an app is connected to ShotManager.

To proceed, the user needs to lock onto a spot. This can be done in 2 ways:

  • Press ‘A’ on Artoo. Orbit will record its current ROI.
  • Drag/move the map until the orbit point on the map aligns with the desired orbit ROI,and then select either the app banner or ‘A’ on Artoo. This will send a SOLO_MESSAGE_LOCATION to ShotManager, which will be the ROI.

In any case, if an initial ROI is set for Orbit, it will send this location back to the app via a SOLO_MESSAGE_LOCATION message.

At any point, if the user hits ‘FLY’, it will exit orbit and ShotManager will send a SOLO_MESSAGE_GET_CURRENT_SHOT with -1 to the app.

The app can send SOLO_SHOT_OPTIONS to ShotManager to change cruise speed. If the user hits the "Pause" button on Artoo, ShotManager will adjust cruiseSpeed to 0.0 and send SOLO_SHOT_OPTIONS to the app. Hitting “pause” again will set cruiseSpeed to the original speed and send it to the app.

When an initial ROI is set, ShotManager will set Solo to Guided and the copter will be in orbit mode.

During orbit mode, the app can send a SOLO_MESSAGE_LOCATION to update the ROI location and begin a new orbit around the new ROI. Note this differs from Follow mode, which sends new points but does not reset the orbit.

Prior to the ROI being set, the app should show on the app the projected ROI of orbit. This is not passed from ShotManager to the app, so the app should calculate it. This calculation works as follows:

if camera.getPitch(self.vehicle) > SHALLOW_ANGLE_THRESHOLD (-60):
    loc = location_helpers.newLocationFromAzimuthAndDistance(self.vehicle.location, camera.getYaw(self.vehicle), FAILED_ROI_DISTANCE  (20.0))
else:
    loc = roi.CalcCurrentROI(self.vehicle)

Buttons for cruising work as they do in cable cam.

Follow

Follow is a special case of orbit. It works the same way except instead of setting or locking onto an roi, it uses the phone’s GPS. In order to do this, it needs to connect to a udp port on ShotManager.

First the app should tell ShotManager to enter the Follow shot via SOLO_MESSAGE_SET_CURRENT_SHOT. Follow is not enterable via Artoo.

Then the app should begin to stream positions in SOLO_MESSAGE_LOCATION packets to ShotManager on port 14558. It should stream locations at 25 Hz, because that is the update loop rate of ShotManager.

Buttons for cruising work as they do in cable cam.

Cable cam (legacy)

Either the app can request that cable cam starts (via SOLO_MESSAGE_SET_CURRENT_SHOT) or the user can initiate from Artoo, in which case ShotManager will tell the app via a SOLO_MESSAGE_GET_CURRENT_SHOT. This only works if an app is connected to ShotManager.

To proceed, the user needs to record two locations.

The app can tell ShotManager to record a point using SOLO_MESSAGE_RECORD_POSITION, but it should always wait to receive a SOLO_CABLE_CAM_WAYPOINT before proceeding.

Otherwise, a user can Press ‘A’ to record a point on Artoo.

If a user tries to record two points on top of each other, the second one overwrites the first. To inform the app, ShotManager will send a SOLO_MESSAGE_GET_CURRENT_SHOT with -1 as a shot which should tell the app to exit cable cam, then a SOLO_MESSAGE_GET_CURRENT_SHOT with 2 to reenter cable cam, and then a SOLO_CABLE_CAM_WAYPOINT to reflect the new starting point of the cable.

At any point, if the user hits ‘FLY’, it will exit cable cam and ShotManager will send a SOLO_MESSAGE_GET_CURRENT_SHOT with -1 to the app.

After the second point is recorded, ShotManager will send a SOLO_CABLE_CAM_OPTIONS to the app so the app can retrieve the memorized yaw direction. The app can send SOLO_CABLE_CAM_OPTIONS to ShotManager to change any of the options. If the user hits the Pause button on Artoo, ShotManager will adjust cruiseSpeed to 0.0 and send SOLO_CABLE_CAM_OPTIONS to the app. Hitting “pause” again will set cruiseSpeed to the original speed and send it to the app. Two camera pointing modes are supported: interpolated camera ('interpolate cam') and user-controller camera ('free cam'). The 'camInterpolate' value in SOLO_CABLE_CAM_OPTIONS is a boolean that switches between these modes.

When the second point is recorded, ShotManager will set Solo to Guided and the copter will be on the cable.

Zip Line

Zip Line is an infinitly long cable generated from Yaw/Pitch of the camera and initial location of the vehicle. Once created the pilot and fly the cable with the right stick and aim the camera with the left stick.

Pressing A will allow the pilot to create a new Zip Line based on the camera pose. Pressing B will toggle from the default Free Look camera to a spot lock camera. The ROI will be sent to the app as a location.

The SOLO_ZIPLINE_OPTIONS packet is sent to control the speed and the option to take the camera pitch into account when creating Zip Lines.

Pano

Pano is constructed as 3 seperate modes - Video, Cylindical and Spherical.

The Pano shot starts in a Setup state. Once the user chooses their point of view and options, the begin the shot. Once the shot is finished it exits to Fly or in the case of the Video Pan option, it will run indefinitely.

The SOLO_PANO_OPTIONS packet contains the desired type of Pano, the state (0 = setup, 1 = run), the Field of View in degrees for the cylinder shot, and the speed of the Video Pan for Pause/Resume functionality.

Button mapping

The button mappings for ‘A’ and ‘B’ are stored on Solo. The app should poll these settings using SOLO_GET_BUTTON_SETTING, upon which ShotManager will send the current setting back.

If a user changes the setting, the app can set it with SOLO_SET_BUTTON_SETTING.

We only use "Press" events at the moment.

Protocol

All communication follows this TLV format (little endian).

Packet
{
    messageType : UInt32
    messageLength: UInt32
    messageValue : <n bytes as defined by messageLength>
}

Message definitions

General messages

We only have a few message types at the moment.

SOLO_MESSAGE_GET_CURRENT_SHOT

  • Sent by: ShotManager to App.
  • Valid: ???

Sent from Solo to app when it enters a shot.

SL version: 1.0

Field Type Value/Description
messageType UInt32 0
messageLength UInt32 4
messageValue ??? Index of shot (SELFIE = 0, ORBIT=1, CABLECAM=2, FOLLOW=5)

SOLO_MESSAGE_SET_CURRENT_SHOT

  • Sent by: App to ShotManager.
  • Valid: ???

Sent from app to Solo to request that Solo begin a shot.

SL version: 1.0

Field Type Value/Description
messageType UInt32 1
messageLength UInt32 4
messageValue ??? Index of shot (SELFIE = 0, ORBIT=1, CABLECAM=2, FOLLOW=5, MPCABLECAM=6)

SOLO_MESSAGE_LOCATION

  • Sent by: App to ShotManager.
  • Valid: ???

Sent from app to Solo to communicate a location.

SL version: 1.0

Field Type Value/Description
messageType UInt32 2
messageLength UInt32 20
latitude Double
longitude Double
altitude Float Altitude in meters.

SOLO_MESSAGE_RECORD_POSITION

  • Sent by: App to ShotManager.
  • Valid: ???

Sent from app to Solo to request recording of a position.

SL version: 1.0

Field Type Value/Description
messageType UInt32 3
messageLength UInt32 0

SOLO_CABLE_CAM_OPTIONS

  • Sent by: Bidirectional.
  • Valid: Both App and ShotManager can send anytime after a legacy cable has been setup.

Sent from app to Solo to set Cable cam (legacy) options. Sent from Solo to app to update cruise speed.

SL version: 1.0

Field Type Value/Description
messageType UInt32 4
messageLength UInt32 8
camInterpolation Short 1 - On, 0 - Off
yawDirection Short 1 - Clockwise, 0 - Counterclockwise
cruiseSpeed Float Cruise speed in meters/second.

SOLO_GET_BUTTON_SETTING

  • Sent by: Bidirectional.
  • Valid: ???

Sent from app to Solo to request Button mapping setting. Sent from Solo to app as a response.

SL version: 1.0

Field Type Value/Description
messageType UInt32 5
messageLength UInt32 16
button Int32 ButtonPower = 0 ButtonFly = 1 ButtonRTL = 2 ButtonLoiter = 3 ButtonA = 4 ButtonB = 5 ButtonPreset1 = 6 ButtonPreset2 = 7 ButtonCameraClick = 8
event Int32 Press = 0 Release = 1 ClickRelease = 2 Hold = 3 LongHold = 4 DoubleClick = 5
shot Int32 shot index, -1 if none. One of shot/mode should be -1, and the other should have a value
mode Int32 APM mode index, -1 if none

SOLO_SET_BUTTON_SETTING

  • Sent by: App to ShotManager.
  • Valid: ???

Sent from app to Solo to set a Button mapping setting.

SL version: 1.0

Field Type Value/Description
messageType UInt32 6
messageLength UInt32 16
button Int32 ButtonPower = 0 ButtonFly = 1 ButtonRTL = 2 ButtonLoiter = 3 ButtonA = 4 ButtonB = 5 ButtonPreset1 = 6 ButtonPreset2 = 7 ButtonCameraClick = 8
event Int32 Press = 0 Release = 1 ClickRelease = 2 Hold = 3 LongHold = 4 DoubleClick = 5
shot Int32 shot index, -1 if none. One of shot/mode should be -1, and the other should have a value
mode Int32 APM mode index, -1 if none

SOLO_PAUSE

  • Sent by: ShotManager <-> App.
  • Valid: Valid only in a shot.

Used by ShotManager or app to transmit a pause request.

SL version: 2.4.0+

Field Type Value/Description
messageType UInt32 7
messageLength UInt32 8

SOLO_FOLLOW_OPTIONS

  • Sent by: Bidirectional.
  • Valid: ???

Sent from app to Solo or vice versa to transmit follow options.

SL version: 1.0

Field Type Value/Description
messageType UInt32 19
messageLength UInt32 8
cruiseSpeed Float Cruise speed in meters/second.
inLookAtMode int 1 - yes, 0 - no

SL version: 2.x.x ???

Field Type Value/Description
messageType UInt32 119
messageLength UInt32 12
cruiseSpeed Float Cruise speed in meters / second.
inLookAtMode int 1 - yes, 0 - no.
freeLookMode int 1 - yes, 0 - no

SOLO_SHOT_OPTIONS

  • Sent by: ???
  • Valid: ???

Sent from app to Solo or vice versa to transmit selfie options.

These messages only go from ShotManager -> App.

SL version: 1.0

Field Type Value/Description
messageType UInt32 20
messageLength UInt32 4
cruiseSpeed Float Cruise speed in meters/second.

SOLO_SHOT_ERROR

  • Sent by: ShotManager -> App.
  • Valid: ???

Sent from Solo to app when entry into a shot was attempted but rejected due to poor EKF, being unarmed, or RTL.

SL version: 1.0

Field Type Value/Description
messageType UInt32 21
messageLength UInt32 4
errorType Int32 BAD_EKF = 0, UNARMED = 1, RTL = 2

SOLO_MESSAGE_SHOTMANAGER_ERROR

  • Sent by: ShotManager -> App.
  • Valid: ???

Debugging tool - ShotManager sends this to the app when it has hit an exception.

SL version: 1.0

Field Type Value/Description
messageType UInt32 1000
messageLength UInt32 N (length of exceptStr)
exceptStr Exception info and stacktrace

SOLO_CABLE_CAM_WAYPOINT

  • Sent by: ShotManager -> App.
  • Valid: ???

Send the app our cable cam waypoint when it’s recorded.

SL version: 1.0

Field Type Value/Description
messageType UInt32 1001
messageLength UInt32 28
latitude Double
longitude Double
altitude Float Altitude in metres
degreesYaw Float Yaw in degrees.
pitch Float Camera pitch in degrees.

SOLO_SECOND_PHONE_NOTIFICATION

  • Sent by: ShotManager -> App.
  • Valid: ???

ShotManager sends this to the app when the app is not the first to connect to ShotManager (it’s connection will be closed).

SL version: ???

Field Type Value/Description
messageType UInt32 1002
messageLength UInt32 0

SOLO_ZIPLINE_OPTIONS

  • Sent by: Bidirectional.
  • Valid: ???

Sent from app to Solo or vice versa to transmit zip line options.

Field Type Value/Description
messageType UInt32 119
messageLength UInt32 6
cruiseSpeed Float Cruise speed in meters / second.
is3D UInt8 1 - yes, 0 - no.
camPointing UInt8 1 -Spot Lock, 0 - Free Look

SOLO_PANO_OPTIONS

  • Sent by: Bidirectional.
  • Valid: ???

Sent from app to Solo or vice versa to transmit Pano options.

Field Type Value/Description
messageType UInt32 119
messageLength UInt32 8
panoType UInt8 1 - yes, 0 - no.
run state UInt8 1 - run, 0 - stop, reset
cylinder_fov Int16 91 to 360
is3D UInt8 1 - yes, 0 - no.
degSecondYaw Float -60 to 60 (deg/sec)

Multipoint cable cam (SOLO_SPLINE_) messages

SOLO_SPLINE_RECORD

  • Sent by: App -> ShotManager.
  • Valid: ???

Tells ShotManager to enter Record mode and clear the current Path.

SL version: ???

Field Type Value/Description
messageType UInt32 50
messageLength UInt32 0

SOLO_SPLINE_PLAY

  • Sent by: Bidirectional.
  • Valid: ???

Bidirectional message: sent by the app to tell ShotManager to enter Play mode; sent by ShotManager to the app after entering Play mode in response to an Artoo button press.

In both cases, ShotManager follows this message with a sequence of SOLO_SPLINE_POINT messages to transmit the current Path to the app.

ShotManager will only enter Play mode if a valid Path exists in Record mode; otherwise, the behavior is undefined. This implies that the app must only send this message when it knows a valid Path exists.

SL version: ???

Field Type Value/Description
messageType UInt32 51
messageLength UInt32 0

SOLO_SPLINE_POINT

  • Sent by: Bidirectional.
  • Valid: ???

Transmits proposed or actual Keypoints on the current camera Path.

ShotManager uses this message for two things:

  1. To transmit Keypoints it creates in response to Artoo button presses or SOLO_MESSAGE_RECORD_POSITION messages.
  2. To confirm the validity of Keypoints it receives from the app; to ACK those Keypoints.

When ShotManager creates a Keypoint, it assigns an index. When the app receives this message and a Keypoint with the index already exists, it updates the Keypoint to the values in this message; it replaces the existing Keypoint.

The app uses this message to load Keypoints from previously recorded, known valid Paths into ShotManager.

In every case, ShotManager sends a SOLO_SPLINE_POINT message back to the app to confirm it was able to create the Keypoint. If it can't create the Keypoint, it sends a failure status.

SL version: ???

Field Type Value/Description
messageType UInt32 52
messageLength UInt32 44
version UInt16 0
absAltReference Float Absolute altitude of home location when cable was recorded, in meters.
index Int32 starting at 0
latitude Double Latitude (decimal degrees).
longitude Double Longitude (decimal degrees).
altitude Float Relative altitude in metres.
pitch Float Pitch (degrees).
yaw Float Yaw (degrees)
uPosition Float The parametric offset of the Keypoint along the Path. In Record mode, these values have no meaning since they can't be assigned until the Path is complete. In Play mode, *ShotManager* assigns these values and sends messages to the app. The app never creates these values.
status Int16 ShotManager sends this value to indicate success or failure when creating a Keypoint. Negative values are failure; 0 or positive is success. 
<p><b>Error codes:</b></p>
  • -1 : mode error (tried setting a spline point when we were already in PLAY mode).
  • -2 : keypoint too close to a previous keypoint
  • -3 : duplicate index error (received multiple Keypoints for a single index)
  • -4..-MAXINT16 : unspecified failure

SOLO_SPLINE_ATTACH

  • Sent by: Bidirectional.
  • Valid: Only after Path is loaded.

This message directs ShotManager to fly to a Keypoint on the Path. After the vehicle reaches this point, ShotManager responds with a SOLO_SPLINE_ATTACH to indicate that it has reached the Path and is prepared to receive SOLO_SPLINE_SEEK messages.

When ShotManager enters playback mode, the vehicle may or may not be positioned on the path -- from the app’s point of view, the actual position and velocity of the vehicle with respect to the Path are unknown.

How ShotManager directs the vehicle to the Path is implementation specific and not defined.

This message is only valid once after a Path is loaded. There is no corresponding "detach" message -- the vehicle stays attached until playback mode is exited.

SL version: ???

Field Type Value/Description
messageType UInt32 57
messageLength UInt32 4
keypointIndex Int32 The index of the Keypoint on the currently defined Path to which *ShotManager* will attach (or did attach, for ShotManager to App packets).

SOLO_SPLINE_SEEK

  • Sent by: App -> ShotManager.
  • Valid: Valid only in Play mode when the vehicle is attached to the Path. Ignored at other times.

This message tells ShotManager to fly the vehicle to a position along the normalized length of the Path. The cruiseState value indicates pause/play state of the vehicle. This does not overwrite the stored cruise speed set by SOLO_SPLINE_PATH_SETTINGS.

SL version: ???

Field Type Value/Description
messageType UInt32 53
messageLength UInt32 8
uPosition Float A parametric offset along the Path normalized to (0,1).
cruiseState Int32 Used by the app to determine the state of the cruise play/pause buttons.
  • -1: Cruising to the start of the cable(negative cruise speed).
  • 0 : Not moving/paused (cruise speed == 0). (DEFAULT)
  • 1 : Cruising to the end of the cable (positive cruise speed).

SOLO_SPLINE_PLAYBACK_STATUS

  • Sent by: ShotManager to App.
  • Valid: Valid only in Play mode.

ShotManager sends this message to the app to indicate the vehicle's parametric position and cruise state along the Path. The source, precision, and accuracy of these values is solely determined by ShotManager. They are for visualization in the app, but not control; they are intended to convey the information, "the vehicle was at this point, trying to move at this cruise speed when the message was sent" with as much certainty as practically possible. But there are no guarantees.

The frequency at which ShotManager sends these messages is currently 10Hz. At a minimum, in playback mode ShotManager will send this message:

  • When the vehicle attaches to the path in response to the first SOLO_SPLINE_SEEK message received after entering Play mode.
  • Each time the vehicle passes a Keypoint, including the beginning and end of the path
  • When the vehicle starts or stops moving.
  • When the vehicle’s parametric acceleration exceeds a threshold value:

The threshold is implementation-specific, exact value TBD (ideally, it should be "tuneable").

SL version: ???

Field Type Value/Description
messageType UInt32 54
messageLength UInt32 8
uPosition Float A parametric offset along the Path normalized to (0,1).
cruiseState Int32 Used by the app to determine the state of the cruise play/pause buttons.
  • -1: Cruising to the start of the cable (negative cruise speed).
  • 0 : Not moving/paused (cruise speed == 0). (DEFAULT)
  • 1 : Cruising to the end of the cable (positive cruise speed).

SOLO_SPLINE_PATH_SETTINGS

  • Sent by: App -> ShotManager. Optional.
  • Valid: Valid only in Play mode.

The app sends this message to configure various aspects of how ShotManager interprets the current Path. This message is optional -- if the app never sends it, ShotManager will use the assumed default values listed below. Values stay in effect until the Path is reset by a SOLO_SPLINE_RECORD message.

SL version: ???

Field Type Value/Description
messageType UInt32 55
messageLength UInt32 8
cameraControl Int32
  • 0 : *ShotManager* controls camera interpolation; automatically points camera
  • 1 : No camera interpolation - camera is controlled with Artoo only.
    • (DEFAULT 0)
desiredTime Float The app-requested total cable completion time, in seconds.

SOLO_SPLINE_DURATIONS

  • Sent by: ShotManager -> App.
  • Valid: Valid only in Play mode.

Used by ShotManager to transmit time information about the currently defined Path. It is sent at least once after ShotManager enters play mode to define the time bounds for the Path.

Optionally, ShotManager can also resend the information any time previous values become invalid. For example, high winds or a low battery might mean that the previously reported maxUVelocity isn’t realistic; ShotManager would re-send the message to advise the app to change its estimates.

SL version: ???

Field Type Value/Description
messageType UInt32 56
messageLength UInt32 8
minTime Float The estimated time (in seconds) it will take to fly the entire path at maximum speed.
maxTime Float The estimated time (in seconds) it will take to fly the entire path at minimum speed.

GoPro messages

GOPRO_SET_ENABLED

  • Sent by: ???
  • Valid: ???

Enable/disable GoPro communications altogether. This can be useful in dealing with a camera model that is incapable of handling communications. This value will be stored by ShotManager and persist between boots.

SL version: ???

Field Type Value/Description
messageType UInt32 5000
messageLength UInt32 4
enabled UInt32 0 off, 1 on

GOPRO_SET_REQUEST

  • Sent by: App -> ShotManager
  • Valid: ???

Wrapper for the MAVLink version. See here for reference on this message. The app will send this to ShotManager via TCP, so that ShotManager can handle this without using the lossy MAVLink connection. This is a legacy request that will only be able to set the first byte of the request payload.

SL version: 1.1.12

Field Type Value/Description
messageType UInt32 5001
messageLength UInt32 4
command unsigned short
value unsigned short

GOPRO_RECORD

  • Sent by: ???
  • Valid: ???

Higher level call, allowing the app/Artoo to issue a record command in either video or stills mode. ShotManager will handle issuing the command

SL version: 1.1.12

Field Type Value/Description
messageType UInt32 5003
messageLength UInt32 4
on/off UInt32 0: Stop recording 1: Start recording 2: Toggle recording

GOPRO_STATE

  • Sent by: ShotManager -> App
  • Valid: ???

Attempt to encapsulate all state that an app might want to know about the GoPro in one packet. This is automatically sent from ShotManager to the app any time a change in its contents occurs. Otherwise the app can explicitly request it to be sent by sending ShotManager a GOPRO_REQUEST_STATE packet (see below).

Because of a bug in earlier versions of the iOS app, the new ShotManager will actually send two packets: a V1 packet with the original field contents and a new V2 packet with the extended GoPro state.

SL version: 1.1.12 (Incomplete handling in SL version 1.1.12)

Field Type Value/Description
messageType UInt32 5005: V1 spec 5006: V2 spec
messageLength UInt32 36
Version UInt8 Which version of the spec?

Version 1 only supplies data through capture mode. Version 2 adds additional fields.
Model UInt8 Model of the camera. Currently not supported.
Status UInt8 Status: 0: STATUS_NO_GOPRO 1: STATUS_INCOMPATIBLE_GOPRO 2: STATUS_GOPRO_CONNECTED 3: STATUS_ERROR
Recording UInt8 0: not recording 1: recording
Capture Mode UInt8 CAPTURE_MODE_VIDEO = 0 CAPTURE_MODE_PHOTO = 1 CAPTURE_MODE_BURST = 2 (Hero3+ only) CAPTURE_MODE_TIMELAPSE = 3 CAPTURE_MODE_MULTISHOT = 4 (Hero4 only)
NTSC/PAL UInt8 0: NTSC 1: PAL
Video Resolution UInt8
Video FPS UInt8
Video FOV UInt8
Video Low Light UInt8 0: Off 1: On requires compatible video settings
Photo Resolution UInt8
Photo Burst Rate UInt8
Video Protune UInt8 0: Off 1: On requires compatible video settings
Video White Balance UInt8 Hero3 only. Requires protune on.
Video Color UInt8 Hero3 only. Requires protune on.
Video Gain UInt8 Hero3 only. Requires protune on.
Video Sharpness UInt8 Hero3 Only requires protune on
Video Exposure UInt8 Requires protune on.

Hero4 range only from -2.0 to 2.0. Hero3+ from -5.0 to 5.0. We only care about -2.0 to 2.0
Gimbal Enabled UInt8 0: Off 1: On
Extra1 UInt8 Reserved for future use.
Extra2 UInt8 Reserved for future use.
Extra3 UInt8 Reserved for future use.
Extra4 UInt8 Reserved for future use.
Extra5 UInt8 Reserved for future use.
Extra6 UInt8 Reserved for future use.
Extra7 UInt8 Reserved for future use.
Extra1 UInt16 Reserved for future use.
Extra2 UInt16 Reserved for future use.
Extra3 UInt16 Reserved for future use.
Extra4 UInt16 Reserved for future use.
Extra5 UInt16 Reserved for future use.

GOPRO_REQUEST_STATE

  • Sent by: App -> ShotManager
  • Valid: ???

Requests that ShotManager send the app a GOPRO_STATE packet

SL version: 1.2.0

Field Type Value/Description
messageType UInt32 5007
messageLength UInt32 0

GOPRO_SET_EXTENDED_REQUEST

  • Sent by: App -> ShotManager
  • Valid: ???

Wrapper for the MAVLink version. See here for reference on this message. The app will send this to ShotManager via TCP, so that ShotManager can handle this without using the lossy MAVLink connection. This differs from the GOPRO_SET_REQUEST in that all 4 payload bytes can be set.

SL version: 1.3

Field Type Value/Description
messageType UInt32 5009
messageLength UInt32 6
command UInt16
value UInt8[4]

GeoFence messages

GEOFENCE_SET_DATA

  • Sent by: App -> ShotManager.
  • Valid: Always

Sent from app to ShotManager to set geofence data. The data is encapsulated in a JSON blob. There are three keys in the JSON Blob, each of them is an array of polygon's information. They must be of equal sizes. ShotManager will validate this packet and respond with GEOFENCE_SET_ACK with either a positive ack (good data) or negative ack (bad data).

version: v2.4.0+

Field Type Value/Description
messageType UInt32 3000
messageLength UInt32 length of the following JSON blob
JSON blob N/A JSON blob payload

JSON Blob:

Field Type Value/Description
coord JSON Array ordered list of polygon, which is in turn an ordered list of (lat, lon), counter-clockwise vertices of genfence polygon
subCoord JSON Array ordered list of polygon, which is in turn an ordered list of (lat, lon), counter-clockwise vertices of geofence sub polygon
type JSON Array ordered list of polygon types, 1 for exclusive geofence and 0 for inclusive geofence

Example:

data = {
  'coord':    [
                [
                  [37.873391778802457, -122.30124440324217], 
                  [37.873425469262187, -122.30088420379124], 
                  [37.87289578293214, -122.30071240112851], 
                  [37.872942621197538, -122.30124440324217]
                ]
              ],
  'subCoord': [
                [
                  [37.873405777181389, -122.30090131123818], 
                  [37.872916521332435, -122.30074261865762], 
                  [37.872958695063687, -122.3012216429134], 
                  [37.873375815652267, -122.3012216429134]
                ]
              ],
  'type':     [
                0
              ]
        }

GEOFENCE_SET_ACK

  • Sent by: App <- ShotManager.
  • Valid: After GEOFENCE_SET_DATA, GEOFENCE_UPDATE_POLY or GEOFENCE_CLEAR is sent from App to ShotManager

Acknowledge from ShotManager to the App after message from the App. Can either be a positive ack (ShotManager took the change) or negative ack (ShotManger rejected the change).

version: v2.4.0+

Field Type Value/Description
messageType UInt32 3001
messageLength UInt32 3
count UInt16 The total number of polygons existing on ShotManger right now)
valid Bool True: Positive ack / False: Negative ack

GEOFENCE_UPDATE_POLY

  • Sent by: App -> ShotManager.
  • Valid: When ShotManager already has polygon data

Update a polygon, either: 1. Update a vertex; 2. add a new vertex; 3. delete a vertex. The course of action is determined by the first byte after messaegLength. This message is currently not used and is subject to change.

version: v2.4.0+

Field Type Value/Description
messageType UInt32 3002
messageLength UInt32 37
action UInt8 action to be performed, see below
polygonIndex UInt16 Index of target polygon
vertexIndex UInt16 Index of target vertex
lat Double latitude of new coordinate on polygon
lon Double longitude of new coordinate on polygon
subLat Double latitude of new coordinate on subpolygon
subLon Double longitude of new coordinate on subpolygon

Action:

Value Description
0 Update Vertex
1 Add Vertex
2 Remove Vertex, the following four Double will be ignored in this case

GEOFENCE_CLEAR

  • Sent by: App <-> ShotManager.
  • Valid: Always

Either the App or ShotManager can send this message to indicate GeoFence has been cleared on their sides. When this message is sent from App to ShotManager, ShotManager will also send a GEOFENCE_SET_ACK.

version: v2.4.0+

Field Type Value/Description
messageType UInt32 3003
messageLength UInt32 0

GEOFENCE_ACTIVATED

  • Sent by: App <- ShotManager.
  • Valid: Always

ShotManager will send this message to the App every time GeoFence is activating.

version: v2.4.0+

Field Type Value/Description
messageType UInt32 3004
messageLength UInt32 0

Site Scan Inspect (SOLO_INSPECT_) messages

SOLO_INSPECT_START

  • Sent by: App -> ShotManager.
  • Valid: Only once during an Inspect shot.

Sent by the app to ShotManager to notify that the inspect shot is ready to commence and the vehicle should climb to the provided takeoffAlt. Shotmanager will either takeoff or place the vehicle into GUIDED depending on whether the vehicle is already in the air or not.

version: v2.2.0+

Field Type Value/Description
messageType UInt32 10001
messageLength UInt32 4
takeoffAlt Float Relative altitude from takeoff (in meters) that the vehicle should navigate to.

SOLO_INSPECT_SET_WAYPOINT

  • Sent by: App -> ShotManager.
  • Valid: Anytime during the active Inspect shot

Sent by the app to ShotManager to instruct Solo to navigate towards the provided waypoint.

version: v2.2.0+

Field Type Value/Description
messageType UInt32 10002
messageLength UInt32 12
latitude Float Latitude in decimal degrees
longitude Float Longitude in decimal degrees
latitude Float Relative altitude from takeoff (in meters)

SOLO_INSPECT_MOVE_GIMBAL

  • Sent by: App -> ShotManager.
  • Valid: Anytime during the active Inspect shot

Sent by the app to ShotManager to instruct Solo to actuate gimbal to desired orientation.

version: v2.2.0+

Field Type Value/Description
messageType UInt32 10003
messageLength UInt32 12
pitch Float Body-relative pitch in degrees (0 to -90)
roll Float Body-relative roll in degrees
yaw Float Earth frame Yaw (heading) in degrees (0 to 360)

SOLO_INSPECT_MOVE_VEHICLE

  • Sent by: App -> ShotManager.
  • Valid: Anytime during the active Inspect shot

Sent by the app to ShotManager to instruct Solo to move with a certain velocity (body-relative NED frame).

version: v2.2.0+

Field Type Value/Description
messageType UInt32 10004
messageLength UInt32 12
vx Float Desired velocity in body-x (NED)
vy Float Desired velocity in body-y (NED)
vz Float Desired velocity in body-z (NED)

Site Scan Scan (SOLO_SCAN_) messages

SOLO_SCAN_START

  • Sent by: App -> ShotManager.
  • Valid: Only once during a Scan shot.

Sent by the app to ShotManager to notify that the scan shot is ready to commence.

version: v2.2.0+

Field Type Value/Description
messageType UInt32 10101
messageLength UInt32 0

Site Scan Survey (SOLO_SURVEY_) messages

SOLO_SURVEY_START

  • Sent by: App -> ShotManager.
  • Valid: Only once during a Survey shot.

Sent by the app to ShotManager to notify that the survey shot is ready to commence.

version: v2.2.0+

Field Type Value/Description
messageType UInt32 10201
messageLength UInt32 0