Bluetooth Low Energy (BLE) Specification v2.0

58 minute read

About This Page

This page describes the format, capabilities, and use of Bluetooth Low Energy (BLE) as it pertains to communicating with GoPro cameras. Messages are sent using either TLV or Protobuf format.

General

Communicating with a GoPro camera via Bluetooth Low Energy involves writing to Bluetooth characteristics and, typically, waiting for a response notification from a corresponding characteristic. The camera organizes its Generic Attribute Profile (GATT) table by broad features: AP control, control & query, etc.

Note: All byte ordering is in Big Endian unless otherwise noted.

Supported Cameras

Below is a table of cameras that support GoPro's public BLE API:

Model ID Model Code Marketing Name Minimal Firmware Version
62 H23.01 HERO12 Black v01.10.00
60 H22.03 HERO11 Black Mini v01.10.00
58 H22.01 HERO11 Black v01.10.00
57 H21.01 HERO10 Black v01.10.00
55 HD9.01 HERO9 Black v01.70.00

Services and Characteristics

Note: GP-XXXX is shorthand for GoPro's 128-bit UUIDs: b5f9xxxx-aa8d-11e3-9046-0002a5d5c51b

Service UUID Service Characteristic UUID Description Permissions
GP-0001 GoPro WiFi Access Point GP-0002 WiFi AP SSID Read / Write
GP-0003 WiFi AP Password Read / Write
GP-0004 WiFi AP Power Write
GP-0005 WiFi AP State Read / Indicate
GP-0090 GoPro Camera Management GP-0091 Network Management Command Write
GP-0092 Network Management Response Notify
FEA6 Control & Query GP-0072 Command Write
GP-0073 Command Response Notify
GP-0074 Settings Write
GP-0075 Settings Response Notify
GP-0076 Query Write
GP-0077 Query Response Notify

Packet Headers

The Bluetooth Low Energy protocol limits messages to 20 bytes per packet. To accommodate this limitation, GoPro cameras use start packets and continuation packets. If a message is 20 bytes or fewer, it can be sent with a single packet containing the start packet header. If a message is longer than 20 bytes, it must be chunked into multiple packets with the first packet containing a start packet header and subsequent packets containing continuation packet headers.

All lengths are in bytes.

Packet Header Format

Message sending and receiving is accomplished by prepending General (5-bit), Extended (13-bit), Extended (16-bit), or Continuation headers onto each packet depending on the message size.

General (5-bit) Messages (Send and Receive)

Messages that are 31 bytes or fewer can be sent or received using the following format:

Byte 1
7 6 5 4 3 2 1 0
0: Start 00: General Message Length: 5 bits

Extended (13-bit) Messages (Send and Receive)

Messages that are 8191 bytes or fewer can be sent or received using the following format:

Quickstart Tip: Always use Extended (13-bit) packet headers when sending messages to avoid having to work with multiple packet header formats.

Byte 1 Byte 2
7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0
0: Start 01: Extended (13-bit) Message Length: 13 bits

Extended (16-bit) Messages (Receive only)

If a message is 8192 bytes or longer, the camera will respond using the format below.

Note: This format cannot be used for sending messages to the camera.

Byte 1 Byte 2 Byte 3
7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0
0: Start 10: Extended (16-bit) Message Length: 16 bits

Continuation Packets (Send and Receive)

When sending or receiving a message that is longer than 20 bytes, the message must be split into N packets with packet 1 containing a start packet header and packets 2..N containing a continuation packet header.

Note: Counters start at 0x0 and reset after 0xF.

Byte 1
7 6 5 4 3 2 1 0
1: Continuation Counter (4-bit)

Example: Packetizing a 5-bit General Message

Message Length: 17 bytes

Message: 01:02:03:04:05:06:07:08:09:0A:0B:0C:0D:0E:0F:10:11

Packet Type Byte(s) Description
1 Header 11 (0) start packet
(00) 5-bit General message
(10001) message length: 17
Payload 01:02:03:04:05:06:07:08:09:0A:0B:0C:0D:0E:0F:10:11 Message

Example: Packetizing a 13-bit Extended Message

Message Length: 50 bytes

Message: 01:02:03:04:05:06:07:08:09:0A:0B:0C:0D:0E:0F:10:11:12:13:14:15:16:17:18:19:1A:1B:1C:1D:1E:1F:20:21:22:23:24:25:26:27:28:29:2A:2B:2C:2D:2E:2F:30:31:32

Packet Type Byte(s) Description
1 Header 20:32 (0) start packet
(01) 13-bit Extended message
(0000000110010) message length: 50
Payload 01:02:03:04:05:06:07:08:09:0A:0B:0C:0D:0E:0F:10:11:12 Message (chunk 1 of 3)
2 Header 80 (0) continuation packet
(000) ignored
(0000) counter: 0
Payload 13:14:15:16:17:18:19:1A:1B:1C:1D:1E:1F:20:21:22:23:24:25 Message (chunk 2 of 3)
3 Header 81 (0) continuation packet
(000) ignored
(0001) counter: 1
Payload 26:27:28:29:2A:2B:2C:2D:2E:2F:30:31:32 Message (chunk 3 of 3)

Example: Depacketizing a Mutli-Packet Message

Packets Received: 5

Once the packet headers are identified and removed from each packet, the complete response message can be assembled by concatenating the remaining packet data in the order it was received.

Packet Byte(s) Header
1 20:57:01:02:03:04:05:06:07:08:09:0A:0B:0C:0D:0E:0F:10:11:12 20:57
(0) start packet
(01) 13-bit Extended message
(0000001010111) message length: 87
2 80:13:14:15:16:17:18:19:1A:1B:1C:1D:1E:1F:20:21:22:23:24:25 80
(1) continuation packet
(000) ignored
(0000) counter: 0
3 81:26:27:28:29:2A:2B:2C:2D:2E:2F:30:31:32:33:34:35:36:37:38 81
(1) continuation packet
(000) ignored
(0001) counter: 1
4 82:39:3A:3B:3C:3D:3E:3F:40:41:42:43:44:45:46:47:48:49:4A:4B 82
(1) continuation packet
(000) ignored
(0010) counter: 2
5 83:4C:4D:4E:4F:50:51:52:53:54:55:56:57 83
(1) continuation packet
(000) ignored
(0011) counter: 3

Discovery, Connection and Pairing

Advertisements

The camera will send BLE advertisements while it is ON and for the first 8 hours after the camera is put to sleep. During this time, the camera is discoverable and can be connected to. If the camera is in sleep mode, connecting to it will cause the camera to wake and boot up.

Pairing

In order to communicate with a GoPro camera via BLE, a client must first be paired with the camera. The pairing procedure must be done once for each new client. If the camera is factory reset, all clients will need to pair again. To pair with the camera, use the UI to put it into pairing mode, connect via BLE and then initiate pairing. The camera will whitelist the client so subsequent connections do not require pairing.

Steps

Discovery of and connection to the GoPro camera can be done as follows:

  1. Put the camera into pairing mode
  2. Scan to discover peripherals (which can be narrowed by limiting to peripherals that advertise service FEA6)
  3. Connect to the peripheral
  4. Finish pairing with the peripheral
  5. Discover all advertised services and characteristics
  6. Subscribe to notifications from all characteristics that have the notify flag set

Sending and Receiving Messages

In order to enable two-way communication with a GoPro camera, clients must connect to the camera and subscribe to characteristics that have the notify flag set. Messages are sent to the camera by writing to a write-enabled UUID and then waiting for a notification from the corresponding response UUID. Response notifications indicate whether the message was valid and will be (asynchronously) processed. For example, to send a camera control command, a client should write to GP-0072 and then wait for a response notification from GP-0073.

Depending on the camera's state, it may not be ready to accept specific commands. This ready state is dependent on the System Busy and the Encoding Active status flags. For example:

  • System Busy flag is set while loading presets, changing settings, formatting sdcard, ...
  • Encoding Active flag is set while capturing photo/video media

If the system is not ready, it should reject an incoming command; however, best practice is to always wait for the System Busy and Encode Active flags to be unset before sending messages other than get status/setting queries.

Parsing Responses

In order to communicate fully with the camera, the user will need to be able to parse response and event notifications in TLV or Protobuf format as needed.

TLV and Protobuf responses have very different formats. Parsing TLV data requires a parser to be written locally. Parsing Protobuf data can be done using code generated from Protobuf files linked in this document. Typically, the camera will send TLV responses/events for commands sent in TLV format and Protobuf responses/events for commands sent in Protobuf format.

The pseudocode and flowcharts below refer to the following tables:

Pseudocode

Below is pseudocode describing how to determine whether a respose is TLV or Protobuf and then parse it appropriately.

Camera sends response R (array of bytes) from UUID U (string) with payload P (array of bytes)
// Is it a Protobuf response?
for each row in the Protobuf IDs table {
    F (int) = Feature ID
    A (array of int) = Action IDs
    if P[0] == F and P[1] in A {
        R is a protobuf message
        Match Feature ID P[0] and Action ID P[1] to a Response message in the Protobuf Commands Table
        Use matched Response message to parse payload into useful data structure
        Exit
    }
}
// Nope. It is a TLV response
if U == GP-0072 (Command) {
    Parse using Command Response Format table
}
else if U == GP-0074 (Settings) {
    Parse using Settings Response Format table
}
else if U == GP-0076 (Query) {
    Parse using Query Response Format table
}
Exit

Flowchart

Below is a flowchart describing how to determine whether a respose is TLV or Protobuf and then parse it appropriately.

Receive response RExtract payload P P[0] == Feature ID from row N of Protobuf IDs TableANDP[1] in Action IDs list from row N of Protobuf IDs Table yesnoR is a protobuf messageR is a TLV messageResponse RResponse UUIDR is a Command responseR is a Settings responseR is a Query responseParse accordinglyFeature ID = P[0]Action ID = P[1]Use: Protobuf Commands TableParse using appropriate protobuf messageKnowledge!GP-0072(Control)GP-0076(Query)GP-0074(Settings)TLV messageProtobuf message

Keep Alive

In order to maximize battery life, GoPro cameras automatically go to sleep after some time. This logic is handled by a combination of an Auto Power Down setting which most (but not all) cameras support and a Keep Alive message that the user can regularly send to the camera. The camera will automatically go to sleep if both timers reach zero.

The Auto Power Down timer is reset when the user taps the LCD screen, presses a button on the camera or programmatically (un)sets the shutter, sets a setting, or loads a Preset.

The Keep Alive timer is reset when the user sends a keep alive message.

The best practice to prevent the camera from inadvertently going to sleep is to start sending Keep Alive messages every 3.0 seconds after a connection is established.

Command

UUID Write Response UUID Response
GP-0074 03:5B:01:42 GP-0075 02:5B:00

Limitations

HERO12 Black

  • The camera will reject requests to change settings while encoding; for example, if Hindsight feature is active, the user cannot change settings

HERO11 Black Mini

  • The camera will reject requests to change settings while encoding; for example, if Hindsight feature is active, the user cannot change settings

HERO11 Black

  • The camera will reject requests to change settings while encoding; for example, if Hindsight feature is active, the user cannot change settings

HERO10 Black

  • The camera will reject requests to change settings while encoding; for example, if Hindsight feature is active, the user cannot change settings

HERO9 Black

  • The camera will reject requests to change settings while encoding; for example, if Hindsight feature is active, the user cannot change settings

General

  • Unless changed by the user, GoPro cameras will automatically power off after some time (e.g. 5min, 15min, 30min). The Auto Power Down watchdog timer can be reset by sending periodic keep-alive messages to the camera. It is recommended to send a keep-alive at least once every 120 seconds.
  • In general, querying the value for a setting that is not associated with the current preset/core mode results in an undefined value. For example, the user should not try to query the current Photo Digital Lenses (FOV) value while in Standard preset (Video mode).

Type Length Value

GoPro's BLE protocol comes in two flavors: TLV (Type Length Value) and Protobuf. This section describes TLV style messaging.

Note: All TLV messages (payloads) must be packetized and wrapped with Packet Headers as outlined in this document.

Commands

The table below contains command IDs supported by Open GoPro. Command messages are sent to GP-0072 and responses/notifications are received on GP-0073.

Command ID Description
0x01 Set shutter
0x05 Sleep
0x0D Set Date/Time
0x0E Get Date/Time
0x0F Set Local Date/Time
0x10 Get Local Date/Time
0x17 AP Control
0x18 Media: HiLight Moment
0x3C Get Hardware Info
0x3E Presets: Load Group
0x40 Presets: Load
0x50 Analytics
0x51 Open GoPro

Command Format

Header/Length Command ID Parameter Length Parameter Value
1-2 bytes 1 byte 1 byte Variable length

Command Response

The GoPro camera sends responses to most commands received, indicating whether the command was valid and will be processed or not.

Unless indicated otherwise in the Quick Reference table below, command responses use the format below.

Command Response Format

Header/Length Command ID Response Code Response
1-2 bytes 1 byte 1 byte Variable length

Command Response Error Codes

Error Code Description
0 Success
1 Error
2 Invalid Parameter
3..255 Reserved

Commands Quick Reference

Below is a table of commands that can be sent to the camera and how to send them.
* Indicates that item is experimental
Indicates support for all Open GoPro firmware versions.
Indicates a lack of support for all Open GoPro firmware versions.
>= vXX.YY.ZZ indicates support for firmware versions equal to or newer than vXX.YY.ZZ

ID Command Description Request Response HERO12 Black HERO11 Black Mini HERO11 Black HERO10 Black HERO9 Black
0x01 Set shutter Shutter: off 03:01:01:00 02:01:00
0x01 Set shutter Shutter: on 03:01:01:01 02:01:00
0x05 Sleep Put camera to sleep 01:05 02:05:00
0x0D Set Date/Time Set date/time to 2023-01-31 03:04:05 09:0D:07:07:E7:01:1F:03:04:05 02:0D:00
0x0E Get Date/Time Get date/time 01:0E Complex
0x0F Set Local Date/Time Set local date/time to: 2023-01-31 03:04:05 (utc-02:00) (dst: on) 0C:0F:0A:07:E7:01:1F:03:04:05:FF:88:01 02:0F:00
0x10 Get Local Date/Time Get local date/time 01:10 Complex
0x17 AP Control Ap mode: off 03:17:01:00 02:17:00
0x17 AP Control Ap mode: on 03:17:01:01 02:17:00
0x18 Media: HiLight Moment Hilight moment during encoding 01:18 02:18:00
0x3C Get Hardware Info Get camera hardware info 01:3C Complex
0x3E Presets: Load Group Video 04:3E:02:03:E8 02:3E:00
0x3E Presets: Load Group Photo 04:3E:02:03:E9 02:3E:00
0x3E Presets: Load Group Timelapse 04:3E:02:03:EA 02:3E:00
0x40 Presets: Load Example preset id: 0x1234ABCD 06:40:04:12:34:AB:CD 02:40:00
0x50 Analytics Set third party client 01:50 02:50:00
0x51 Open GoPro Get version 01:51 Complex

Complex Command Inputs

Set Local Date/Time

The timezone is a two byte UTC offset in minutes and must be sent in Two's Complement form.

Complex Command Responses

Below are clarifications for complex camera responses

Get Hardware Info

Response Packet Response Byte(s) Description
1 20 Start packet
51 Response length
3C:00 Command 3C sent successfully
04 Length of model number
00:00:00:37 Model ID
0B Length of model id
48:45:52:4F:58:20:42:6C:61:63 “HEROX Blac”
2 80 Continuation packet
6B “k”
04 Length of board type
30:78:30:35 “0x05”
0F Length of firmware version
48:44:58:2E:58:58:2E:58:58:2E:58:58 “HDX.XX.XX.XX”
3 81 Continuation packet (1)
2E:58:58 “.XX”
0E Length of serial number
58:58:58:58:58:58:58:58:58:58:58:58:58:58 “XXXXXXXXXXXXXX”
0A Length of AP SSID
4 82 Continuation packet (2)
47:50:32:34:35:30:58:58:58:58 “GP2450XXXX”
0C AP MAC Address length
58:58:58:58:58:58:58:58 “XXXXXXXX”
5 83 Continuation packet (3)
58:58:58:58 “XXXX”

Open GoPro Version

Given the response 06:51:00:01:01:01:00, the Open GoPro version would be vXX.YY.

Response Byte(s) Description
06 Packet length
51 Command ID
00 Status (OK)
01 Length of major version
01 Major version: 1
01 Length of minor version
00 Minor version: 0

Get Date/Time

Given the response 0B:0E:00:08:07:E5:01:02:03:04:05:06, the date/time would be 2022-01-02 03:04:05 (Saturday).

Response Byte(s) Description
0B Packet length
0E Command ID
00 Status (OK)
08 Date length (bytes)
07:E6 Year
01 Month
02 Day
03 Hour
04 Minute
05 Second
06 Day of the week (Sun=0, Sat=6)

Get Local Date/Time (with Timezone and DST)

Given the response 0D:10:00:0A:07:E6:01:02:03:04:05:FE:20:01, the date/time would be 2022-01-02 03:04:05-0800 (DST: ON).

Response Byte(s) Description
0D Packet length
10 Command ID
00 Status (OK)
0A Date length (bytes)
07:E6 Year
01 Month
02 Day
03 Hour
04 Minute
05 Second
FE:20 UTC offset in minutes (Two’s Complement)
01 DST: ON

Settings

GoPro settings can be configured using the GP-Settings (GP-0074) UUID. Setting status is returned on GP-Settings-Status (GP-0075) UUID.

Settings Request Format

This will configure a setting on the camera. Only one setting may be sent on a packet (GATT notify or write-no-response), although multiple packets may be sent back-to-back.

Request Length Setting ID Setting Value Length Setting Value
1-2 bytes 1 byte 1 byte (variable length)

Settings Response Format

Response Length Setting ID Response Code
1 byte 1 byte 1 byte

Settings Quick Reference

All settings are sent to UUID GP-0074. All values are hexadecimal and length are in bytes.
* Indicates that item is experimental
Indicates support for all Open GoPro firmware versions.
Indicates a lack of support for all Open GoPro firmware versions.
>= vXX.YY.ZZ indicates support for firmware versions equal to or newer than vXX.YY.ZZ

Setting ID Setting Option Request Response HERO12 Black HERO11 Black Mini HERO11 Black HERO10 Black HERO9 Black
2 Resolution Set video resolution (id: 2) to 4k (id: 1) 03:02:01:01 02:02:00
2 Resolution Set video resolution (id: 2) to 2.7k (id: 4) 03:02:01:04 02:02:00
2 Resolution Set video resolution (id: 2) to 2.7k 4:3 (id: 6) 03:02:01:06 02:02:00
2 Resolution Set video resolution (id: 2) to 1440 (id: 7) 03:02:01:07 02:02:00
2 Resolution Set video resolution (id: 2) to 1080 (id: 9) 03:02:01:09 02:02:00
2 Resolution Set video resolution (id: 2) to 4k 4:3 (id: 18) 03:02:01:12 02:02:00
2 Resolution Set video resolution (id: 2) to 5k (id: 24) 03:02:01:18 02:02:00
2 Resolution Set video resolution (id: 2) to 5k 4:3 (id: 25) 03:02:01:19 02:02:00
2 Resolution Set video resolution (id: 2) to 5.3k 8:7 (id: 26) 03:02:01:1A 02:02:00
2 Resolution Set video resolution (id: 2) to 5.3k 4:3 (id: 27) 03:02:01:1B 02:02:00
2 Resolution Set video resolution (id: 2) to 4k 8:7 (id: 28) 03:02:01:1C 02:02:00
2 Resolution Set video resolution (id: 2) to 4k 9:16 (id: 29) 03:02:01:1D 02:02:00
2 Resolution Set video resolution (id: 2) to 1080 9:16 (id: 30) 03:02:01:1E 02:02:00
2 Resolution Set video resolution (id: 2) to 5.3k (id: 100) 03:02:01:64 02:02:00
2 Resolution Set video resolution (id: 2) to 5.3k 16:9 (id: 101) 03:02:01:65 02:02:00
2 Resolution Set video resolution (id: 2) to 4k 16:9 (id: 102) 03:02:01:66 02:02:00
2 Resolution Set video resolution (id: 2) to 4k 4:3 (id: 103) 03:02:01:67 02:02:00
2 Resolution Set video resolution (id: 2) to 2.7k 16:9 (id: 104) 03:02:01:68 02:02:00
2 Resolution Set video resolution (id: 2) to 2.7k 4:3 (id: 105) 03:02:01:69 02:02:00
2 Resolution Set video resolution (id: 2) to 1080 16:9 (id: 106) 03:02:01:6A 02:02:00
3 Frames Per Second Set video fps (id: 3) to 240 (id: 0) 03:03:01:00 02:03:00
3 Frames Per Second Set video fps (id: 3) to 120 (id: 1) 03:03:01:01 02:03:00
3 Frames Per Second Set video fps (id: 3) to 100 (id: 2) 03:03:01:02 02:03:00
3 Frames Per Second Set video fps (id: 3) to 60 (id: 5) 03:03:01:05 02:03:00
3 Frames Per Second Set video fps (id: 3) to 50 (id: 6) 03:03:01:06 02:03:00
3 Frames Per Second Set video fps (id: 3) to 30 (id: 8) 03:03:01:08 02:03:00
3 Frames Per Second Set video fps (id: 3) to 25 (id: 9) 03:03:01:09 02:03:00
3 Frames Per Second Set video fps (id: 3) to 24 (id: 10) 03:03:01:0A 02:03:00
3 Frames Per Second Set video fps (id: 3) to 200 (id: 13) 03:03:01:0D 02:03:00
59 Auto Power Down Set auto power down (id: 59) to never (id: 0) 03:3B:01:00 01:3B:00 >= v02.10.00
59 Auto Power Down Set auto power down (id: 59) to 1 min (id: 1) 03:3B:01:01 01:3B:00 >= v02.10.00 >= v02.01.00
59 Auto Power Down Set auto power down (id: 59) to 5 min (id: 4) 03:3B:01:04 01:3B:00 >= v02.10.00
59 Auto Power Down Set auto power down (id: 59) to 15 min (id: 6) 03:3B:01:06 01:3B:00
59 Auto Power Down Set auto power down (id: 59) to 30 min (id: 7) 03:3B:01:07 01:3B:00
59 Auto Power Down Set auto power down (id: 59) to 8 seconds (id: 11) 03:3B:01:0B 01:3B:00 >= v02.10.00
59 Auto Power Down Set auto power down (id: 59) to 30 seconds (id: 12) 03:3B:01:0C 01:3B:00 >= v02.10.00
108 Aspect Ratio Set video aspect ratio (id: 108) to 4:3 (id: 0) 03:6C:01:00 02:6C:00
108 Aspect Ratio Set video aspect ratio (id: 108) to 16:9 (id: 1) 03:6C:01:01 02:6C:00
108 Aspect Ratio Set video aspect ratio (id: 108) to 8:7 (id: 3) 03:6C:01:03 02:6C:00
108 Aspect Ratio Set video aspect ratio (id: 108) to 9:16 (id: 4) 03:6C:01:04 02:6C:00
121 Video Digital Lenses Set video digital lenses (id: 121) to wide (id: 0) 03:79:01:00 02:79:00
121 Video Digital Lenses Set video digital lenses (id: 121) to narrow (id: 2) 03:79:01:02 02:79:00
121 Video Digital Lenses Set video digital lenses (id: 121) to superview (id: 3) 03:79:01:03 02:79:00
121 Video Digital Lenses Set video digital lenses (id: 121) to linear (id: 4) 03:79:01:04 02:79:00
121 Video Digital Lenses Set video digital lenses (id: 121) to max superview (id: 7) 03:79:01:07 02:79:00 >= v02.00.00
121 Video Digital Lenses Set video digital lenses (id: 121) to linear + horizon leveling (id: 8) 03:79:01:08 02:79:00
121 Video Digital Lenses Set video digital lenses (id: 121) to hyperview (id: 9) 03:79:01:09 02:79:00
121 Video Digital Lenses Set video digital lenses (id: 121) to linear + horizon lock (id: 10) 03:79:01:0A 02:79:00
121 Video Digital Lenses Set video digital lenses (id: 121) to max hyperview (id: 11) 03:79:01:0B 02:79:00
122 Photo Digital Lenses Set photo digital lenses (id: 122) to narrow (id: 19) 03:7A:01:13 02:7A:00
122 Photo Digital Lenses Set photo digital lenses (id: 122) to max superview (id: 100) 03:7A:01:64 02:7A:00
122 Photo Digital Lenses Set photo digital lenses (id: 122) to wide (id: 101) 03:7A:01:65 02:7A:00
122 Photo Digital Lenses Set photo digital lenses (id: 122) to linear (id: 102) 03:7A:01:66 02:7A:00
123 Time Lapse Digital Lenses Set time lapse digital lenses (id: 123) to narrow (id: 19) 03:7B:01:13 02:7B:00
123 Time Lapse Digital Lenses Set time lapse digital lenses (id: 123) to max superview (id: 100) 03:7B:01:64 02:7B:00
123 Time Lapse Digital Lenses Set time lapse digital lenses (id: 123) to wide (id: 101) 03:7B:01:65 02:7B:00
123 Time Lapse Digital Lenses Set time lapse digital lenses (id: 123) to linear (id: 102) 03:7B:01:66 02:7B:00
128 Media Format Set media format (id: 128) to time lapse video (id: 13) 03:80:01:0D 02:80:00
128 Media Format Set media format (id: 128) to time lapse photo (id: 20) 03:80:01:14 02:80:00
128 Media Format Set media format (id: 128) to night lapse photo (id: 21) 03:80:01:15 02:80:00
128 Media Format Set media format (id: 128) to night lapse video (id: 26) 03:80:01:1A 02:80:00
134 Anti-Flicker Set setup anti flicker (id: 134) to 60hz (id: 2) 03:86:01:02 02:86:00
134 Anti-Flicker Set setup anti flicker (id: 134) to 50hz (id: 3) 03:86:01:03 02:86:00
135 Hypersmooth Set video hypersmooth (id: 135) to off (id: 0) 03:87:01:00 02:87:00
135 Hypersmooth Set video hypersmooth (id: 135) to low (id: 1) 03:87:01:01 02:87:00
135 Hypersmooth Set video hypersmooth (id: 135) to high (id: 2) 03:87:01:02 02:87:00
135 Hypersmooth Set video hypersmooth (id: 135) to boost (id: 3) 03:87:01:03 02:87:00
135 Hypersmooth Set video hypersmooth (id: 135) to auto boost (id: 4) 03:87:01:04 02:87:00
135 Hypersmooth Set video hypersmooth (id: 135) to standard (id: 100) 03:87:01:64 02:87:00
150 Horizon Leveling Set video horizon levelling (id: 150) to off (id: 0) 03:96:01:00 02:96:00 >= v02.00.00
150 Horizon Leveling Set video horizon levelling (id: 150) to on (id: 1) 03:96:01:01 02:96:00 >= v02.00.00
150 Horizon Leveling Set video horizon levelling (id: 150) to locked (id: 2) 03:96:01:02 02:96:00
151 Horizon Leveling Set photo horizon levelling (id: 151) to off (id: 0) 03:97:01:00 02:97:00
151 Horizon Leveling Set photo horizon levelling (id: 151) to locked (id: 2) 03:97:01:02 02:97:00
162 Max Lens Set max lens (id: 162) to off (id: 0) 03:A2:01:00 02:A2:00 >= v01.20.00
162 Max Lens Set max lens (id: 162) to on (id: 1) 03:A2:01:01 02:A2:00 >= v01.20.00
167 Hindsight* Set hindsight (id: 167) to 15 seconds (id: 2) 03:A7:01:02 02:A7:00
167 Hindsight* Set hindsight (id: 167) to 30 seconds (id: 3) 03:A7:01:03 02:A7:00
167 Hindsight* Set hindsight (id: 167) to off (id: 4) 03:A7:01:04 02:A7:00
171 Interval Set photo single interval (id: 171) to off (id: 0) 03:AB:01:00 02:AB:00
171 Interval Set photo single interval (id: 171) to 0.5s (id: 2) 03:AB:01:02 02:AB:00
171 Interval Set photo single interval (id: 171) to 1s (id: 3) 03:AB:01:03 02:AB:00
171 Interval Set photo single interval (id: 171) to 2s (id: 4) 03:AB:01:04 02:AB:00
171 Interval Set photo single interval (id: 171) to 5s (id: 5) 03:AB:01:05 02:AB:00
171 Interval Set photo single interval (id: 171) to 10s (id: 6) 03:AB:01:06 02:AB:00
171 Interval Set photo single interval (id: 171) to 30s (id: 7) 03:AB:01:07 02:AB:00
171 Interval Set photo single interval (id: 171) to 60s (id: 8) 03:AB:01:08 02:AB:00
171 Interval Set photo single interval (id: 171) to 120s (id: 9) 03:AB:01:09 02:AB:00
171 Interval Set photo single interval (id: 171) to 3s (id: 10) 03:AB:01:0A 02:AB:00
172 Duration Set photo interval duration (id: 172) to off (id: 0) 03:AC:01:00 02:AC:00
172 Duration Set photo interval duration (id: 172) to 15 seconds (id: 1) 03:AC:01:01 02:AC:00
172 Duration Set photo interval duration (id: 172) to 30 seconds (id: 2) 03:AC:01:02 02:AC:00
172 Duration Set photo interval duration (id: 172) to 1 minute (id: 3) 03:AC:01:03 02:AC:00
172 Duration Set photo interval duration (id: 172) to 5 minutes (id: 4) 03:AC:01:04 02:AC:00
172 Duration Set photo interval duration (id: 172) to 15 minutes (id: 5) 03:AC:01:05 02:AC:00
172 Duration Set photo interval duration (id: 172) to 30 minutes (id: 6) 03:AC:01:06 02:AC:00
172 Duration Set photo interval duration (id: 172) to 1 hour (id: 7) 03:AC:01:07 02:AC:00
172 Duration Set photo interval duration (id: 172) to 2 hours (id: 8) 03:AC:01:08 02:AC:00
172 Duration Set photo interval duration (id: 172) to 3 hours (id: 9) 03:AC:01:09 02:AC:00
173 Video Performance Mode Set video performance mode (id: 173) to maximum video performance (id: 0) 03:AD:01:00 02:AD:00 >= v01.16.00
173 Video Performance Mode Set video performance mode (id: 173) to extended battery (id: 1) 03:AD:01:01 02:AD:00 >= v01.16.00
173 Video Performance Mode Set video performance mode (id: 173) to tripod / stationary video (id: 2) 03:AD:01:02 02:AD:00 >= v01.16.00
175 Controls Set controls (id: 175) to easy (id: 0) 03:AF:01:00 02:AF:00
175 Controls Set controls (id: 175) to pro (id: 1) 03:AF:01:01 02:AF:00
176 Speed Set speed (id: 176) to 8x ultra slo-mo (id: 0) 03:B0:01:00 02:B0:00
176 Speed Set speed (id: 176) to 4x super slo-mo (id: 1) 03:B0:01:01 02:B0:00
176 Speed Set speed (id: 176) to 2x slo-mo (id: 2) 03:B0:01:02 02:B0:00
176 Speed Set speed (id: 176) to 1x (low light) (id: 3) 03:B0:01:03 02:B0:00
176 Speed Set speed (id: 176) to 4x super slo-mo (ext. batt) (id: 4) 03:B0:01:04 02:B0:00
176 Speed Set speed (id: 176) to 2x slo-mo (ext. batt) (id: 5) 03:B0:01:05 02:B0:00
176 Speed Set speed (id: 176) to 1x (ext. batt, low light) (id: 6) 03:B0:01:06 02:B0:00
176 Speed Set speed (id: 176) to 8x ultra slo-mo (50hz) (id: 7) 03:B0:01:07 02:B0:00
176 Speed Set speed (id: 176) to 4x super slo-mo (50hz) (id: 8) 03:B0:01:08 02:B0:00
176 Speed Set speed (id: 176) to 2x slo-mo (50hz) (id: 9) 03:B0:01:09 02:B0:00
176 Speed Set speed (id: 176) to 1x (low light, 50hz) (id: 10) 03:B0:01:0A 02:B0:00
176 Speed Set speed (id: 176) to 4x super slo-mo (ext. batt, 50hz) (id: 11) 03:B0:01:0B 02:B0:00
176 Speed Set speed (id: 176) to 2x slo-mo (ext. batt, 50hz) (id: 12) 03:B0:01:0C 02:B0:00
176 Speed Set speed (id: 176) to 1x (ext. batt, low light, 50hz) (id: 13) 03:B0:01:0D 02:B0:00
176 Speed Set speed (id: 176) to 8x ultra slo-mo (ext. batt) (id: 14) 03:B0:01:0E 02:B0:00 >= v02.01.00
176 Speed Set speed (id: 176) to 8x ultra slo-mo (ext. batt, 50hz) (id: 15) 03:B0:01:0F 02:B0:00 >= v02.01.00
176 Speed Set speed (id: 176) to 8x ultra slo-mo (long. batt) (id: 16) 03:B0:01:10 02:B0:00 >= v02.01.00
176 Speed Set speed (id: 176) to 4x super slo-mo (long. batt) (id: 17) 03:B0:01:11 02:B0:00 >= v02.01.00
176 Speed Set speed (id: 176) to 2x slo-mo (long. batt) (id: 18) 03:B0:01:12 02:B0:00 >= v02.01.00
176 Speed Set speed (id: 176) to 1x (long. batt, low light) (id: 19) 03:B0:01:13 02:B0:00 >= v02.01.00
176 Speed Set speed (id: 176) to 8x ultra slo-mo (long. batt, 50hz) (id: 20) 03:B0:01:14 02:B0:00 >= v02.01.00
176 Speed Set speed (id: 176) to 4x super slo-mo (long. batt, 50hz) (id: 21) 03:B0:01:15 02:B0:00 >= v02.01.00
176 Speed Set speed (id: 176) to 2x slo-mo (long. batt, 50hz) (id: 22) 03:B0:01:16 02:B0:00 >= v02.01.00
176 Speed Set speed (id: 176) to 1x (long. batt, low light, 50hz) (id: 23) 03:B0:01:17 02:B0:00 >= v02.01.00
176 Speed Set speed (id: 176) to 2x slo-mo (4k) (id: 24) 03:B0:01:18 02:B0:00 >= v02.01.00
176 Speed Set speed (id: 176) to 4x super slo-mo (2.7k) (id: 25) 03:B0:01:19 02:B0:00 >= v02.01.00
176 Speed Set speed (id: 176) to 2x slo-mo (4k, 50hz) (id: 26) 03:B0:01:1A 02:B0:00 >= v02.01.00
176 Speed Set speed (id: 176) to 4x super slo-mo (2.7k, 50hz) (id: 27) 03:B0:01:1B 02:B0:00 >= v02.01.00
176 Speed Set speed (id: 176) to 1x speed / low light (id: 28) 03:B0:01:1C 02:B0:00
176 Speed Set speed (id: 176) to 1x speed / low light (id: 29) 03:B0:01:1D 02:B0:00
176 Speed Set speed (id: 176) to 2x slo-mo (id: 30) 03:B0:01:1E 02:B0:00
176 Speed Set speed (id: 176) to 2x slo-mo (id: 31) 03:B0:01:1F 02:B0:00
176 Speed Set speed (id: 176) to 1x speed / low light (id: 32) 03:B0:01:20 02:B0:00
176 Speed Set speed (id: 176) to 1x speed / low light (id: 33) 03:B0:01:21 02:B0:00
176 Speed Set speed (id: 176) to 2x slo-mo (id: 34) 03:B0:01:22 02:B0:00
176 Speed Set speed (id: 176) to 2x slo-mo (id: 35) 03:B0:01:23 02:B0:00
176 Speed Set speed (id: 176) to 1x speed / low light (id: 36) 03:B0:01:24 02:B0:00
176 Speed Set speed (id: 176) to 1x speed / low light (id: 37) 03:B0:01:25 02:B0:00
176 Speed Set speed (id: 176) to 1x speed / low light (id: 38) 03:B0:01:26 02:B0:00
176 Speed Set speed (id: 176) to 1x speed / low light (id: 39) 03:B0:01:27 02:B0:00
176 Speed Set speed (id: 176) to 2x slo-mo (id: 40) 03:B0:01:28 02:B0:00
176 Speed Set speed (id: 176) to 2x slo-mo (id: 41) 03:B0:01:29 02:B0:00
176 Speed Set speed (id: 176) to 2x slo-mo (id: 42) 03:B0:01:2A 02:B0:00
176 Speed Set speed (id: 176) to 2x slo-mo (id: 43) 03:B0:01:2B 02:B0:00
176 Speed Set speed (id: 176) to 1x speed / low light (id: 44) 03:B0:01:2C 02:B0:00
176 Speed Set speed (id: 176) to 1x speed / low light (id: 45) 03:B0:01:2D 02:B0:00
176 Speed Set speed (id: 176) to 1x speed / low light (id: 46) 03:B0:01:2E 02:B0:00
176 Speed Set speed (id: 176) to 1x speed / low light (id: 47) 03:B0:01:2F 02:B0:00
177 Enable Night Photo Set enable night photo (id: 177) to off (id: 0) 03:B1:01:00 02:B1:00
177 Enable Night Photo Set enable night photo (id: 177) to on (id: 1) 03:B1:01:01 02:B1:00
178 Wireless Band Set wireless band (id: 178) to 2.4ghz (id: 0) 03:B2:01:00 02:B2:00
178 Wireless Band Set wireless band (id: 178) to 5ghz (id: 1) 03:B2:01:01 02:B2:00
179 Trail Length Set trail length (id: 179) to short (id: 1) 03:B3:01:01 02:B3:00
179 Trail Length Set trail length (id: 179) to long (id: 2) 03:B3:01:02 02:B3:00
179 Trail Length Set trail length (id: 179) to max (id: 3) 03:B3:01:03 02:B3:00
180 Video Mode Set video mode (id: 180) to highest quality (id: 0) 03:B4:01:00 02:B4:00
180 Video Mode Set video mode (id: 180) to extended battery (id: 1) 03:B4:01:01 02:B4:00
180 Video Mode Set video mode (id: 180) to extended battery (green icon) (id: 101) 03:B4:01:65 02:B4:00 >= v02.01.00
180 Video Mode Set video mode (id: 180) to longest battery (green icon) (id: 102) 03:B4:01:66 02:B4:00 >= v02.01.00
182 Bit Rate Set system video bit rate (id: 182) to standard (id: 0) 03:B6:01:00 02:B6:00
182 Bit Rate Set system video bit rate (id: 182) to high (id: 1) 03:B6:01:01 02:B6:00
183 Bit Depth Set system video bit depth (id: 183) to 8-bit (id: 0) 03:B7:01:00 02:B7:00
183 Bit Depth Set system video bit depth (id: 183) to 10-bit (id: 2) 03:B7:01:02 02:B7:00
184 Profiles Set video profile (id: 184) to standard (id: 0) 03:B8:01:00 02:B8:00
184 Profiles Set video profile (id: 184) to hdr (id: 1) 03:B8:01:01 02:B8:00
184 Profiles Set video profile (id: 184) to log (id: 2) 03:B8:01:02 02:B8:00
185 Aspect Ratio Set video easy aspect ratio (id: 185) to widescreen (id: 0) 03:B9:01:00 02:B9:00
185 Aspect Ratio Set video easy aspect ratio (id: 185) to mobile (id: 1) 03:B9:01:01 02:B9:00
185 Aspect Ratio Set video easy aspect ratio (id: 185) to universal (id: 2) 03:B9:01:02 02:B9:00
186 Video Mode Set video easy presets (id: 186) to highest quality (id: 0) 03:BA:01:00 02:BA:00
186 Video Mode Set video easy presets (id: 186) to standard quality (id: 1) 03:BA:01:01 02:BA:00
186 Video Mode Set video easy presets (id: 186) to basic quality (id: 2) 03:BA:01:02 02:BA:00
187 Lapse Mode Set multi shot easy presets (id: 187) to timewarp (id: 0) 03:BB:01:00 02:BB:00
187 Lapse Mode Set multi shot easy presets (id: 187) to star trails (id: 1) 03:BB:01:01 02:BB:00
187 Lapse Mode Set multi shot easy presets (id: 187) to light painting (id: 2) 03:BB:01:02 02:BB:00
187 Lapse Mode Set multi shot easy presets (id: 187) to vehicle lights (id: 3) 03:BB:01:03 02:BB:00
187 Lapse Mode Set multi shot easy presets (id: 187) to max timewarp (id: 4) 03:BB:01:04 02:BB:00
187 Lapse Mode Set multi shot easy presets (id: 187) to max star trails (id: 5) 03:BB:01:05 02:BB:00
187 Lapse Mode Set multi shot easy presets (id: 187) to max light painting (id: 6) 03:BB:01:06 02:BB:00
187 Lapse Mode Set multi shot easy presets (id: 187) to max vehicle lights (id: 7) 03:BB:01:07 02:BB:00
188 Aspect Ratio Set multi shot easy aspect ratio (id: 188) to widescreen (id: 0) 03:BC:01:00 02:BC:00
188 Aspect Ratio Set multi shot easy aspect ratio (id: 188) to mobile (id: 1) 03:BC:01:01 02:BC:00
188 Aspect Ratio Set multi shot easy aspect ratio (id: 188) to universal (id: 2) 03:BC:01:02 02:BC:00
189 Max Lens Mod Set system addon lens active (id: 189) to none (id: 0) 03:BD:01:00 02:BD:00
189 Max Lens Mod Set system addon lens active (id: 189) to max lens 1.0 (id: 1) 03:BD:01:01 02:BD:00
189 Max Lens Mod Set system addon lens active (id: 189) to max lens 2.0 (id: 2) 03:BD:01:02 02:BD:00
190 Max Lens Mod Enable Set system addon lens status (id: 190) to off (id: 0) 03:BE:01:00 02:BE:00
190 Max Lens Mod Enable Set system addon lens status (id: 190) to on (id: 1) 03:BE:01:01 02:BE:00
191 Photo Mode Set photo easy presets (id: 191) to super photo (id: 0) 03:BF:01:00 02:BF:00
191 Photo Mode Set photo easy presets (id: 191) to night photo (id: 1) 03:BF:01:01 02:BF:00
192 Aspect Ratio Set multi shot nlv aspect ratio (id: 192) to 4:3 (id: 0) 03:C0:01:00 02:C0:00
192 Aspect Ratio Set multi shot nlv aspect ratio (id: 192) to 16:9 (id: 1) 03:C0:01:01 02:C0:00
192 Aspect Ratio Set multi shot nlv aspect ratio (id: 192) to 8:7 (id: 3) 03:C0:01:03 02:C0:00
193 Framing Set video easy framing (id: 193) to widescreen (id: 0) 03:C1:01:00 02:C1:00
193 Framing Set video easy framing (id: 193) to vertical (id: 1) 03:C1:01:01 02:C1:00
193 Framing Set video easy framing (id: 193) to full frame (id: 2) 03:C1:01:02 02:C1:00

Camera Capabilities

Camera capabilities usually change from one camera to another and often change from one release to the next. Below are documents that detail whitelists for basic video settings for every supported camera release.

Note about Dependency Ordering and Blacklisting

Capability documents define supported camera states. Each state is comprised of a set of setting options that are presented in dependency order. This means each state is guaranteed to be attainable if and only if the setting options are set in the order presented. Failure to adhere to dependency ordering may result in the camera's blacklist rules rejecting a set-setting command.

Example

Camera Command 1 Command 2 Command 3 Command 4 Command 5 Guaranteed Valid?
HERO10 Black Res: 1080 Anti-Flicker: 60Hz (NTSC) FPS: 240 FOV: Wide Hypersmooth: OFF
HERO10 Black FPS: 240 Anti-Flicker: 60Hz (NTSC) Res: 1080 FOV: Wide Hypersmooth: OFF

In the example above, the first set of commands will always work for basic video presets such as Standard.

In the second example, suppose the camera's Video Resolution was previously set to 4K. If the user tries to set Video FPS to 240, it will fail because 4K/240fps is not supported.

Capability Documents

Documents Product Release
capabilities.xlsx
capabilities.json
HERO12 Black v01.10.00
HERO11 Black Mini v02.30.00
v02.20.00
v02.10.00
v02.00.00
v01.10.00
HERO11 Black v02.12.00
v02.10.00
v02.01.00
v01.20.00
v01.12.00
v01.10.00
HERO10 Black v01.50.00
v01.46.00
v01.42.00
v01.40.00
v01.30.00
v01.20.00
v01.16.00
v01.10.00
HERO9 Black v01.72.00
v01.70.00

Spreadsheet Format

The capabilities spreadsheet contains worksheets for every supported release. Each row in a worksheet represents a whitelisted state and is presented in dependency order as outlined above.

JSON Format

The capabilities JSON contains a set of whitelist states for every supported release. Each state is comprised of a list of objects that contain setting and option IDs necessary to construct set-setting commands and are given in dependency order as outlined above.

Below is a simplified example of the capabilities JSON file; a formal schema is also available here: capabilities_schema.json

{
    "(PRODUCT_NAME)": {
        "(RELEASE_VERSION)": {
            "states": [
                [
                    {"setting_name": "(str)", "setting_id": (int), "option_name": "(str)", "option_id": (int)},
                    ...
                ],
                ...
            ],
        },
        ...
    },
    ...
}

Query

The camera provides two basic types of state information: Camera status and settings. Camera status info includes information such as the current preset/mode, whether the system is busy or encoding, remaining sdcard space, etc. Settings info gives the currently selected option for each setting; for example, this includes the current video resolution, frame rate, digital lens (FOV), etc.

Queries are sent to to GP-0076 and responses are received on GP-0077.

Query Command Format

Header/Length Query ID Array of IDs
1-2 bytes 1 byte Variable Length

Query Commands

Note: omitting :xx:... from any (un)register command will result in being (un)registered for all associated values.

Query ID Query Request Notes
0x12 Get setting value(s) nn:12:xx:… nn -> message length
xx -> setting ID
0x12 Get all setting values 01:12
0x13 Get status value(s) nn:13:xx:… nn -> message length
xx -> status ID
0x13 Get all status values 01:13
0x32 Get available option IDs for setting(s) nn:32:xx:… nn -> message length
xx -> setting ID
0x32 Get available option IDs for all settings 01:32
0x52 Register for setting(s) value updates nn:52:xx:… nn -> message length
xx -> setting ID
0x53 Register for status value updates nn:53:xx:… nn -> message length
xx -> status ID
0x62 Register for available option updates for setting(s) nn:62:xx:… nn -> message length
xx -> setting ID
0x72 Unregister for setting updates nn:72:xx:… nn -> message length
xx -> setting ID
0x73 Unregister for status updates nn:73:xx:… nn -> message length
xx -> status ID
0x82 Unregister for available option updates for setting(s) nn:82:xx:… nn -> message length
xx -> setting ID
0x92 Async notification when setting changes
0x93 Async notification when status changes
0xA2 Async notification when available option(s) changed

Query Response Format

There are two types of response notifications:

  • Type 1: Notfication sent in direct response to a get-value or register command
  • Type 2: Notification sent in response to data changing (must be registered to receive)
Message Length Query ID Command Status Status ID Status Value Length Status Value
1-2 bytes 1 byte 1 byte 1 byte 1 byte 1-255 bytes

Multi-Value Responses

When receiving a query response that contains information about more than one setting/status the Status ID, Status Value Length, and Status Value fields become collectively repeatable.

Example:

[MESSAGE LENGTH]:[QUERY ID]:[COMMAND STATUS]:[ID1]:[LENGTH1]:[VALUE1]:[ID2]:[LENGTH2]:[VALUE2]:...

Query ID in Notifications

In order to discern between a Type 1 and a Type 2 response, the camera changes the Query ID for Type 2:

Query Query ID in Command Query ID in Notification
Register for setting(s) value updates 0x52 0x92
Register for status value updates 0x53 0x93
Register for available option updates for setting(s) 0x62 0xA2

Status IDs

Below is a table of supported status IDs.
* Indicates that item is experimental
Indicates support for all Open GoPro firmware versions.
Indicates a lack of support for all Open GoPro firmware versions.
>= vXX.YY.ZZ indicates support for firmware versions equal to or newer than vXX.YY.ZZ

Status ID Name Description Type Values HERO12 Black HERO11 Black Mini HERO11 Black HERO10 Black HERO9 Black
1 Internal battery present Is the system’s internal battery present? boolean 0: False
1: True
2 Internal battery level Rough approximation of internal battery level in bars integer 0: Zero
1: One
2: Two
3: Three
6 System hot Is the system currently overheating? boolean 0: False
1: True
8 System busy Is the camera busy? boolean 0: False
1: True
9 Quick capture active Is Quick Capture feature enabled? boolean 0: False
1: True
10 Encoding active Is the system encoding right now? boolean 0: False
1: True
11 Lcd lock active Is LCD lock active? boolean 0: False
1: True
13 Video progress counter When encoding video, this is the duration (seconds) of the video so far; 0 otherwise integer *
17 Enable Are Wireless Connections enabled? boolean 0: False
1: True
19 State The pairing state of the camera integer 0: Never Started
1: Started
2: Aborted
3: Cancelled
4: Completed
20 Type The last type of pairing that the camera was engaged in integer 0: Not Pairing
1: Pairing App
2: Pairing Remote Control
3: Pairing Bluetooth Device
21 Pair time Time (milliseconds) since boot of last successful pairing complete action integer *
22 State State of current scan for WiFi Access Points. Appears to only change for CAH-related scans integer 0: Never started
1: Started
2: Aborted
3: Canceled
4: Completed
23 Scan time msec The time, in milliseconds since boot that the WiFi Access Point scan completed integer *
24 Provision status WiFi AP provisioning state integer 0: Never started
1: Started
2: Aborted
3: Canceled
4: Completed
26 Remote control version Wireless remote control version integer *
27 Remote control connected Is a wireless remote control connected? boolean 0: False
1: True
28 Pairing Wireless Pairing State integer *
29 Wlan ssid Provisioned WIFI AP SSID. On BLE connection, value is big-endian byte-encoded int string *
30 Ap ssid Camera’s WIFI SSID. On BLE connection, value is big-endian byte-encoded int string *
31 App count The number of wireless devices connected to the camera integer *
32 Enable Is Preview Stream enabled? boolean 0: False
1: True
33 Sd status Primary Storage Status integer -1: Unknown
0: OK
1: SD Card Full
2: SD Card Removed
3: SD Card Format Error
4: SD Card Busy
8: SD Card Swapped
34 Remaining photos How many photos can be taken before sdcard is full integer *
35 Remaining video time How many minutes of video can be captured with current settings before sdcard is full integer *
36 Num group photos How many group photos can be taken with current settings before sdcard is full integer *
37 Num group videos Total number of group videos on sdcard integer *
38 Num total photos Total number of photos on sdcard integer *
39 Num total videos Total number of videos on sdcard integer *
41 Ota status The current status of Over The Air (OTA) update integer 0: Idle
1: Downloading
2: Verifying
3: Download Failed
4: Verify Failed
5: Ready
6: GoPro App: Downloading
7: GoPro App: Verifying
8: GoPro App: Download Failed
9: GoPro App: Verify Failed
10: GoPro App: Ready
42 Download cancel request pending Is there a pending request to cancel a firmware update download? boolean 0: False
1: True
45 Camera locate active Is locate camera feature active? boolean 0: False
1: True
49 Multi shot count down The current timelapse interval countdown value (e.g. 5…4…3…2…1…) integer *
54 Remaining space Remaining space on the sdcard in Kilobytes integer *
55 Supported Is preview stream supported in current recording/mode/secondary-stream? boolean 0: False
1: True
56 Wifi bars WiFi signal strength in bars integer *
58 Num hilights The number of hilights in encoding video (set to 0 when encoding stops) integer *
59 Last hilight time msec Time since boot (msec) of most recent hilight in encoding video (set to 0 when encoding stops) integer *
60 Next poll msec The min time between camera status updates (msec). Do not poll for status more often than this integer *
64 Remaining timelapse time How many min of Timelapse video can be captured with current settings before sdcard is full integer *
65 Exposure select type Liveview Exposure Select Mode integer 0: Disabled
1: Auto
2: ISO Lock
3: Hemisphere
66 Exposure select x Liveview Exposure Select: y-coordinate (percent) percent 0-100
67 Exposure select y Liveview Exposure Select: y-coordinate (percent) percent 0-100
68 Gps status Does the camera currently have a GPS lock? boolean 0: False
1: True
69 Ap state Is the camera in AP Mode? boolean 0: False
1: True
70 Internal battery percentage Internal battery level (percent) percent 0-100
74 Acc mic status Microphone Accesstory status integer 0: Microphone mod not connected
1: Microphone mod connected
2: Microphone mod connected and microphone plugged into Microphone mod
75 Digital zoom Digital Zoom level (percent) percent 0-100
76 Wireless band Wireless Band integer 0: 2.4 GHz
1: 5 GHz
2: Max
77 Digital zoom active Is Digital Zoom feature available? boolean 0: False
1: True
78 Mobile friendly video Are current video settings mobile friendly? (related to video compression and frame rate) boolean 0: False
1: True
79 First time use Is the camera currently in First Time Use (FTU) UI flow? boolean 0: False
1: True
81 Band 5ghz avail Is 5GHz wireless band available? boolean 0: False
1: True
82 System ready Is the system ready to accept commands? boolean 0: False
1: True
83 Batt okay for ota Is the internal battery charged sufficiently to start Over The Air (OTA) update? boolean 0: False
1: True
85 Video low temp alert Is the camera getting too cold to continue recording? boolean 0: False
1: True
86 Actual orientation The rotational orientation of the camera integer 0: 0 degrees (upright)
1: 180 degrees (upside down)
2: 90 degrees (laying on right side)
3: 270 degrees (laying on left side)
88 Zoom while encoding Is this camera capable of zooming while encoding (static value based on model, not settings) boolean 0: False
1: True
89 Current mode Current flatmode ID integer *
93 Active video presets Current Video Preset (ID) integer *
94 Active photo presets Current Photo Preset (ID) integer *
95 Active timelapse presets Current Timelapse Preset (ID) integer *
96 Active presets group Current Preset Group (ID) integer *
97 Active preset Current Preset (ID) integer *
98 Preset modified Preset Modified Status, which contains an event ID and a preset (group) ID integer *
99 Remaining live bursts How many Live Bursts can be captured before sdcard is full integer *
100 Num total live bursts Total number of Live Bursts on sdcard integer *
101 Capture delay active Is Capture Delay currently active (i.e. counting down)? boolean 0: False
1: True
102 Media mod mic status Media mod State integer 0: Media mod microphone removed
2: Media mod microphone only
3: Media mod microphone with external microphone
103 Timewarp speed ramp active Time Warp Speed integer 0: 15x
1: 30x
2: 60x
3: 150x
4: 300x
5: 900x
6: 1800x
7: 2x
8: 5x
9: 10x
10: Auto
11: 1x (realtime)
12: 1/2x (slow-motion)
104 Linux core active Is the system’s Linux core active? boolean 0: False
1: True
105 Camera lens type Camera lens type (reflects changes to setting 162 or setting 189) integer 0: Default
1: Max Lens
2: Max Lens 2.0
106 Video hindsight capture active Is Video Hindsight Capture Active? boolean 0: False
1: True
107 Scheduled preset Scheduled Capture Preset ID integer *
108 Scheduled enabled Is Scheduled Capture set? boolean 0: False
1: True
110 Media mod status Media Mode Status (bitmasked) integer 0: 000 = Selfie mod: 0, HDMI: 0, Media Mod Connected: False
1: 001 = Selfie mod: 0, HDMI: 0, Media Mod Connected: True
2: 010 = Selfie mod: 0, HDMI: 1, Media Mod Connected: False
3: 011 = Selfie mod: 0, HDMI: 1, Media Mod Connected: True
4: 100 = Selfie mod: 1, HDMI: 0, Media Mod Connected: False
5: 101 = Selfie mod: 1, HDMI: 0, Media Mod Connected: True
6: 110 = Selfie mod: 1, HDMI: 1, Media Mod Connected: False
7: 111 = Selfie mod: 1, HDMI: 1, Media Mod Connected: True
111 Sd rating check error Does sdcard meet specified minimum write speed? boolean 0: False
1: True
112 Sd write speed error Number of sdcard write speed errors since device booted integer *
113 Turbo transfer Is Turbo Transfer active? boolean 0: False
1: True
114 Camera control status Camera control status ID integer 0: Camera Idle: No one is attempting to change camera settings
1: Camera Control: Camera is in a menu or changing settings. To intervene, app must request control
2: Camera External Control: An outside entity (app) has control and is in a menu or modifying settings
115 Usb connected Is the camera connected to a PC via USB? boolean 0: False
1: True
116 Allow control over usb Camera control over USB state integer 0: Disabled
1: Enabled
>= v01.30.00
117 Total sd space kb Total SD card capacity in Kilobytes integer *

Protobuf

In order to maximize BLE bandwidth, some messages and their corresponding notifications utilize Google Protobuf (Protocol Buffers).

Open GoPro currently uses Protocol Buffers Version 2.

Note: All Protobuf messages (i.e. payloads, which are serialized protobuf objects) must be packetized and wrapped with Packet Headers as outlined in this document.

Protobuf Message Format

Protobuf communications with the camera differ from TLV-style communications. Rather than having a Type, Length, and Value, GoPro protobuf messages utilize the following:

  1. Feature ID: Indicates command type (e.g. command, setting, query)
  2. Action ID: Specific camera action; value indicates whether message was sent or an (aync) notification was received
  3. Value: Serialized protobuf object

Requests Sent

Message Length Feature ID Action ID Protobuf Bytestream
1-2 bytes 1 byte 1 byte Variable Length

Notifications Received

Message Length Feature ID Response Action ID Protobuf Bytestream
1-2 bytes 1 byte 1 byte Variable Length

See Parsing Responses for details on how to detect and parse a protobuf response.

Protobuf IDs

Below is a table that links Protobuf Feature/Action IDs together with the UUIDs to write to and Response UUIDs to read notifications from. For additional details, see Services and Characteristics.

Feature Feature ID Action IDs UUID Response UUID
Network Management 0x02 0x02, 0x03, 0x04, 0x05, 0x0B, 0x0C, 0x82, 0x83, 0x84, 0x85 GP-0091 GP-0092
Command 0xF1 0x69, 0x6B, 0x79, 0xE9, 0xEB, 0xF9 GP-0072 GP-0073
Query 0xF5 0x72, 0x74, 0xF2, 0xF3, 0xF4, 0xF5 GP-0076 GP-0077

Protobuf Commands

Below is a table of protobuf commands that can be sent to the camera and their expected response.
* Indicates that item is experimental
Indicates support for all Open GoPro firmware versions.
Indicates a lack of support for all Open GoPro firmware versions.
>= vXX.YY.ZZ indicates support for firmware versions equal to or newer than vXX.YY.ZZ

Note: Some protobuf commands currently have no fields, which means they serialize into a 0-byte bytestream. For consistency, best practice is to always serialize the protobuf objects regardless of how many fields they define.

Feature ID Action ID Response Action ID Description Request Response HERO12 Black HERO11 Black Mini HERO11 Black HERO10 Black HERO9 Black
0x02 0x02 0x82 Start scan RequestStartScan ResponseStartScanning
0x0B Async status update NotifStartScanning
0x03 0x83 Get ap entries RequestGetApEntries ResponseGetApEntries
0x04 0x84 Connect RequestConnect ResponseConnect
0x0C Async status update ResponseConnect
0x05 0x85 Connect new RequestConnectNew ResponseConnectNew
0x0C Async status update NotifProvisioningState
0xF1 0x69 0xE9 Request set camera control status RequestSetCameraControlStatus ResponseGeneric >= v01.20.00
0x6B 0xEB Request set turbo active RequestSetTurboActive ResponseGeneric
0x79 0xF9 Request set live stream RequestSetLiveStreamMode ResponseGeneric
0xF5 0x72 0xF2 Request get preset status RequestGetPresetStatus NotifyPresetStatus
0xF3 Async status update NotifyPresetStatus
0x74 0xF4 Request get live stream status RequestGetLiveStreamStatus NotifyLiveStreamStatus
0xF5 Async status update NotifyLiveStreamStatus

Features

Below are details about Open GoPro features.

Presets

The camera organizes modes of operation into presets. A preset is a logical wrapper around a specific camera mode, title, icon, and a set of settings that enhance different styles of capturing media.

Depending on the camera's state, different collections of presets will be available for immediate loading and use. Below is a table of settings that affect the current preset collection and thereby which presets can be loaded:

ID Setting
162 Max Lens
173 Video Performance Mode
175 Controls
177 Enable Night Photo
180 Video Mode
186 Video Mode
187 Lapse Mode
189 Max Lens Mod
190 Max Lens Mod Enable
191 Photo Mode

To determine which presets are available for immediate use, get Preset Status.

Preset Status

All cameras support basic query and subscription mechanics that allow the user to:

  • Get hierarchical data describing the Preset Groups, Presets, and Settings that are available in the camera's current state
  • (Un)register to be notified when a Preset is modified (e.g. resolution changes from 1080p to 4K) or a Preset Group is modified (e.g. presets are reordered/created/deleted)

Preset Status should not be confused with camera status:

  • Preset Status contains information about current preset groups and presets
  • Camera status contains numerous statuses about current settings and camera system state

Preset Groups

Each Preset Group contains an ID, whether additional presets can be added, and an array of existing Presets.

Presets

Each Preset contains information about its ID, associated core mode, title, icon, whether it's a user-defined preset, whether the preset has been modified from its factory-default state (for factory-default presets only) and an array of Settings associated with the Preset.

Important Note: The Preset ID is required to load a Preset via the Presets: Load command.

For details on which cameras are supported and how to get Preset Status, see Protobuf Commands.

Global Behaviors

In order to prevent undefined behavior between the camera and a connected app, simultaneous use of the camera and a connected app is discouraged.

Best practice for synchronizing user/app control is to use the Set Camera Control Status command and corresponding Camera Control Status (CCS) camera statuses in alignment with the finite state machine below:

IDLEControl Status: IdleCAMERA_CONTROLControl Status: Camera ControlEXTERNAL_CONTROLControl Status: External ControlApp sets CCS: IdleUser interacts with cameraUser returns camera to idle screenApp sets CCS: IdleApp sets CCS: External ControlApp sets CCS: IdleUser interacts with cameraUser interacts with cameraApp sets CCS: External ControlUser interacts with camera
Control Status ID
IDLE 0
CONTROL 1
EXTERNAL_CONTROL 2

Set Camera Control Status

This command is used to tell the camera that the app (i.e. External Control) wishes to claim control of the camera. This causes the camera to immediately exit any contextual menus and return to the idle screen. Any interaction with the camera's physical buttons will cause the camera to reclaim control and update control status accordingly. If the user returns the camera UI to the idle screen, the camera updates control status to Idle.

Note:

  • The entity currently claiming control of the camera is advertised in camera status 114
  • Information about whether the camera is in a contextual menu or not is advertised in camera status 63.

For details on which cameras are supported and how to set Camera Control Status, see Protobuf Commands.

Interface with Access Points

The camera supports connecting to access points in Station Mode (STA). This is necessary for features such as Live Streaming, where the camera needs an Internet connection. While in this mode, HTTP command and control of the camera is not available on some cameras.

Scanning for Access Points

In order to scan for Access Points, use the flow below. See Protobuf Commands for command details.

CentralCentralGP-0091GP-0091GP-0092GP-0092RequestStartScanResponseStartScanningscanning_state: EnumScanning.SCANNING_STARTEDloop[until scanning_state == EnumScanning.SCANNING_SUCCESS]Indicates scan is completeSave scan_id, total_entriesNotifStartScanningRequestGetApEntriesUse scan_id, total_entriesResponseGetApEntriesEach ScanEntry contains SSID, signal strength, freq

Scan Results

The ResponseGetApEntries message contains information about each discovered device. This information includes the success of the scan, the scan id used in the original request, and a ScanEntry message, whose definition is nested inside ResponseGetApEntries.

A ScanEntry includes information about a discovered device including its SSID, relative signal strength, signal frequency, and a bitmasked scan_entry_flags value whose individual bits are defined by EnumScanEntryFlags.

Note: When scan_entry_flags contains SCAN_FLAG_CONFIGURED, it is an indication that this network has already been provisioned.

Connect to a New Access Point

To provision and connect the camera to a new Access Point, use RequestConnectNew.

Note: This should only be done once to provision the AP; subsequent connections should use RequestConnect.

CentralCentralGP-0091GP-0091GP-0092GP-0092Scan for Access PointsRequestConnectNewResponseConnectNewprovisioning_state: EnumProvisioning.PROVISIONING_STARTEDloop[until provisioning_state == EnumProvisioning.PROVISIONING_SUCCESS_NEW_AP]NotifProvisionState

Connect to a Provisioned Access Point

To connect the camera to a provisioned Access Point, scan for Access Points and connect using RequestConnect:

CentralCentralGP-0091GP-0091GP-0092GP-0092Scan for Access PointsRequestConnectResponseConnectprovisioning_state: EnumProvisioning.PROVISIONING_STARTEDloop[until provisioning_state == EnumProvisioning.PROVISIONING_SUCCESS_NEW_AP]NotifProvisionState

Disconnect from an Access Point

To disconnect from a connected Access Point and return the camera to AP mode, set AP Control: ON, which disables Station Mode.

CentralCentralGP-0072GP-0072GP-0073GP-0073Scan for Access PointsCamera: STA ModeConnect to a New/Provisioned Access Point03:17:01:01AP Mode: ON02:17:00SuccessCamera: AP ModeDisconnected from Access Point

Turbo Transfer

Some cameras support Turbo Transfer mode, which allows media to be downloaded over WiFi more rapidly. This is done by temporarily modifying low-level settings in the OS to prioritize WiFi offload speeds.

When Turbo Transfer is active, theh camera displays an OSD indicating that media is being transferred in order to prevent the user from inadvertently changing settings or capturing media.

Turbo Transfer should only be used during media offload. It is recommended that the user check for and--if necessary--disable Turbo Transfer on connect. Developers can query whether the camera is currently in Turbo Transfer Mode from camera status 113.

Note:

  • Pressing MODE/POWER or Shutter buttons on the camera will deactivate Turbo Transfer feature.
  • Some cameras are already optimized for WiFi transfer and do not gain additional speed from this feature.

For details on which cameras are supported and how to enable and disable Turbo Transfer, see Protobuf Commands.

Live Streaming

The camera supports the ability to stream to social media platforms such as Twitch, YouTube, Facebook or any other site that accepts RTMP(S) URLs.

For additional details about getting started with RTMP, see How to Stream.

Overview

Live streaming with camera is accomplished as follows:

  1. Put the camera into Station Mode and connect it to an access point (see Interface With Access Points)
  2. Set the Live Stream Mode
  3. Poll for Live Stream Status until the camera indicates it is ready
  4. Set the shutter to begin live streaming
  5. Unset the shutter to stop live streaming

Live Streaming Sequence

CentralCentralGP-0091GP-0091GP-0092GP-0092GP-0072GP-0072GP-0073GP-0073GP-0074GP-0074GP-0075GP-0075GP-0076GP-0076GP-0077GP-0077Set live stream modeRequestSetLiveStreamModeResponseGenericPoll Live Stream Status until readyloop[until LIVE_STREAM_STATE_READY]RequestGetLiveStreamStatusNotifyLiveStreamStatusSet desired settingsloop[until Desired camera state attained]Set settingsuccess responseStart live streamingSet shuttersuccess responseStop live streamingUnset shuttersuccess response

Set Live Stream Mode

Set the live stream mode by sending a RequestSetLiveStreamMode command.

Command and enum details are available in Protobuf Comands.

Parameter Type Description
url string RTMP(S) url used to stream. Set to empty string to invalidate/cancel stream
encode bool Whether to encode video to sdcard while streaming or not
window_size EnumWindowSize Streaming video resolution
minimum_bitrate int32 Desired minimum streaming bitrate (min possible: 800)
maximum_bitrate int32 Desired maximum streaming bitrate (max possible: 8000)
starting_bitrate int32 Initial streaming bitrate (honored if 800 <= value <= 8000)
lens EnumLens Streaming Field of View
cert bytes SSL certificate(s) from a trusted Root CA for streaming services that use encryption (RTMPS)

Note: For RTMPS, the cert parameter must be provided in PEM format.

Get Live Stream Status

Current status of the live stream is obtained by sending a RequestGetLiveStreamStatus command to the camera. This command serves two purposes:

  • Get current state of the live stream
  • (Un)register to be notified when live stream state changes

Responses and notifications come as a NotifyLiveStreamStatus message with properties outlined in the table below.

Command and enum details are available in Protobuf Comands.

Parameter Type Description
live_stream_status EnumLiveStreamStatus Basic streaming state (idle, ready, streaming, failed, etc)
live_stream_error EnumLiveStreamError Error codes for specific streaming errors
live_stream_encode bool Whether camera is encoding video to sdcard while encoding or not
live_stream_bitrate int32 Current streaming bitrate (Kbps)
live_stream_window_size_supported_array EnumWindowSize Defines supported streaming resolutions
live_stream_encode_supported bool Does this camera support encoding while streaming?
live_stream_max_lens_unsupported bool Does camera lack support for streaming with Max Lens feature?
live_stream_minimum_stream_bitrate int32 Minimum possible bitrate (static) (Kbps)
live_stream_maximum_stream_bitrate int32 Maximum possible bitrate (static) (Kbps)
live_stream_lens_supported bool Does camera support multiple streaming FOVs?
live_stream_lens_supported_array EnumLens Defines supported Field of View values