Bluetooth Low Energy (BLE) Specification v2.0

34 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.

Supported Cameras

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

ID Model Marketing Name Minimal Firmware Version
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
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, the packet header rules below are used. All lengths are in bytes. The packet count starts at 0 for the first continuation packet.

Packet Header Format

Byte 1 Byte 2 (optional) Byte 3 (optional)
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 00: General Message Length: 5 bits
0: Start 01: Extended (13-bit) Message Length: 13 bits
0: Start 10: Extended (16-bit) Message Length: 16 bits
0: Start 11: Reserved
1: Continuation

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.

Camera To Enter Pairing Mode
HERO10 Black Swipe down, swipe left » Connections » Connect Device » GoPro Quik App
HERO9 Black Swipe down, swipe left » Connections » Connect Device » GoPro App

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.

Presets

The camera organizes modes of operation into presets. A preset is a logical wrapper around a specific camera flatmode and a collection of settings that target different ways of capturing media.

The set of presets available to load at any moment depends on the value of certain camera settings, which are outlined in the table below.

For per-preset firmware compatibility information, see Commands Quick Reference.

Setting Preset Preset ID
Max Lens: OFF Standard 0x00000000
Activity 0x00000001
Cinematic 0x00000002
Ultra Slo-Mo 0x00000004
Basic 0x00000005
Photo 0x00010000
Live Burst 0x00010001
Burst Photo 0x00010002
Night Photo 0x00010003
Time Warp 0x00020000
Time Lapse 0x00020001
Night Lapse 0x00020002
Max Lens: ON Max Video 0x00030000
Max Photo 0x00040000
Max Timewarp 0x00050000
Video Performance Mode: Maximum Video Performance Standard 0x00000000
Activity 0x00000001
Cinematic 0x00000002
Ultra Slo-Mo 0x00000004
Basic 0x00000005
Photo 0x00010000
Live Burst 0x00010001
Burst Photo 0x00010002
Night Photo 0x00010003
Time Warp 0x00020000
Time Lapse 0x00020001
Night Lapse 0x00020002
Video Performance Mode: Extended Battery Photo 0x00010000
Live Burst 0x00010001
Burst Photo 0x00010002
Night Photo 0x00010003
Time Warp 0x00020000
Time Lapse 0x00020001
Night Lapse 0x00020002
Standard [EB] 0x00080000
Activity [EB] 0x00080001
Cinematic [EB] 0x00080002
Slo-Mo [EB] 0x00080003
Video Performance Mode: Tripod / Stationary Video Photo 0x00010000
Live Burst 0x00010001
Burst Photo 0x00010002
Night Photo 0x00010003
Time Warp 0x00020000
Time Lapse 0x00020001
Night Lapse 0x00020002
4K Tripod 0x00090000
5.3K Tripod 0x00090001

Keep Alive

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, as below. It is recommended to send a keep-alive at least once every 120 seconds.

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

Turbo Transfer

Some cameras support Turbo Transfer mode, which allows media to be downloaded over WiFi more rapidly. This special mode should only be used during media offload. It is recommended that the user check for and--if necessary--disable Turbo Transfer on connect. For details on which cameras are supported and how to enable and disable Turbo Transfer, 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:

Limitations

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/flatmode 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 flatmode).

TLV

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

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
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 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 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 2022-01-02 03:04:05 09:0D:07:07:E6:01:02:03:04:05 02:0D:00
0x0E Get Date/Time Get date/time 01:0E Complex
0x17 AP Control WiFi AP: off 03:17:01:00 02:17:00
0x17 AP Control WiFi AP: 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 Standard 06:40:04:00:00:00:00 02:40:00
0x40 Presets: Load Activity 06:40:04:00:00:00:01 02:40:00
0x40 Presets: Load Cinematic 06:40:04:00:00:00:02 02:40:00
0x40 Presets: Load Ultra Slo-Mo 06:40:04:00:00:00:04 02:40:00 >= v01.16.00
0x40 Presets: Load Basic 06:40:04:00:00:00:05 02:40:00 >= v01.16.00
0x40 Presets: Load Photo 06:40:04:00:01:00:00 02:40:00
0x40 Presets: Load Live Burst 06:40:04:00:01:00:01 02:40:00
0x40 Presets: Load Burst Photo 06:40:04:00:01:00:02 02:40:00
0x40 Presets: Load Night Photo 06:40:04:00:01:00:03 02:40:00
0x40 Presets: Load Time Warp 06:40:04:00:02:00:00 02:40:00
0x40 Presets: Load Time Lapse 06:40:04:00:02:00:01 02:40:00
0x40 Presets: Load Night Lapse 06:40:04:00:02:00:02 02:40:00
0x40 Presets: Load Max Video 06:40:04:00:03:00:00 02:40:00 >= v01.20.00
0x40 Presets: Load Max Photo 06:40:04:00:04:00:00 02:40:00 >= v01.20.00
0x40 Presets: Load Max Timewarp 06:40:04:00:05:00:00 02:40:00 >= v01.20.00
0x40 Presets: Load Standard [EB] 06:40:04:00:08:00:00 02:40:00 >= v01.16.00
0x40 Presets: Load Activity [EB] 06:40:04:00:08:00:01 02:40:00 >= v01.16.00
0x40 Presets: Load Cinematic [EB] 06:40:04:00:08:00:02 02:40:00 >= v01.16.00
0x40 Presets: Load Slo-Mo [EB] 06:40:04:00:08:00:03 02:40:00 >= v01.16.00
0x40 Presets: Load 4K Tripod 06:40:04:00:09:00:00 02:40:00 >= v01.16.00
0x40 Presets: Load 5.3K Tripod 06:40:04:00:09:00:01 02:40:00 >= v01.16.00
0x50 Analytics Set third party client 01:50 02:50:00
0x51 Open GoPro Get version 01:51 Complex

Complex Command Responses

Below are clarifications for complex camera responses

Get Hardware Info

Response Packet Response Byte(s) Description
1 20 Start packet
51 Packet length
3C:00 Command 3C sent successfully
04 Length of model number
00:00:00:13 Model number
0B Length of model name
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 2021-01-02 03:04:05 (Saturday).

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

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 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 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 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 (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 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 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 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 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 (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 (id: 100) 03:02:01:64 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 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 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 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 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 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 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 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 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
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
59 Auto Power Down Set auto power down (id: 59) to never (id: 0) 03:3B:01:00 01:3B:00
59 Auto Power Down Set auto power down (id: 59) to 5 min (id: 4) 03:3B:01:04 01:3B:00
59 Auto Power Down Set auto power down (id: 59) to 5 min (id: 4) 03:3B:01:04 01:3B: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 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 30 min (id: 7) 03:3B:01:07 01:3B: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 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 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 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 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
121 Video Digital Lenses Set video digital lenses (id: 121) to max superview (id: 7) 03:79:01:07 02:79: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 linear + horizon leveling (id: 8) 03:79:01:08 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 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 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 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
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 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 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
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 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 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 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
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 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
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 off (id: 0) 03:87:01:00 02:87:00
135 Hypersmooth Set video hypersmooth (id: 135) to on (id: 1) 03:87:01:01 02:87:00
135 Hypersmooth Set video hypersmooth (id: 135) to on (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 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 boost (id: 3) 03:87:01:03 02:87:00
135 Hypersmooth Set video hypersmooth (id: 135) to standard (id: 100) 03:87:01:64 02:87: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 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
162 Max Lens Set max lens (id: 162) to on (id: 1) 03:A2:01:01 02:A2:00 >= v01.20.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

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
HERO10 Black v01.40.00
v01.30.00
v01.20.00
v01.16.00
v01.10.00
HERO9 Black 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 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. All packets sent and received are in Big Endian.

Query Format

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

Query Commands

All query commands are sent to GP-0076. Responses are received on GP-0077.

Note: omitting :xx:... from (un)register query commands will result in being (un)registered for all possible updates

Query ID Query Request Notes
0x12 Get setting value 02:12:xx xx -> Setting ID
0x12 Get all setting values 01:12
0x13 Get status value 02:13:xx xx -> status code
0x13 Get all status values 01:13
0x52 Register for setting updates nn:52:xx:… nn -> message length
xx -> setting id
0x53 Register for status updates nn:53:xx:… nn -> message length
xx -> status code
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 code

Query Response Format

Query responses are pushed asynchronously in the following scenarios:

  • The user queries for current status/settings
  • The user registers for settings/status updates
  • The user is registered to receive updates for a status/setting and the value changes
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 querying for or receiving a push notifications 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]:...

Push Notification Responses

The Query ID for settings/status push notifications replaces the upper 4 bits with 1001 (nine).

For example, if the original query comand ID was 0x52, the query ID of the push notification will be 0x92.

Status Codes

Below is a table of supported status codes.
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 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
3 External battery present Is an external battery connected? boolean 0: False
1: True
4 External battery level External battery power level in percent percent 0-100
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: Success
1: In Progress
2: Failed
3: Stopped
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/flatmode/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 WiFi radio enabled? 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 *
91 Logs ready Are system logs ready to be downloaded? boolean 0: False
1: True
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) integer 0: Default
1: Max Lens
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
109 Creating preset Is the camera in the process of creating a custom preset? boolean 0: False
1: True
110 Media mod status Media Mode Status (bitmasked) integer 0: Display (selfie) mod: 0, HDMI: 0, Media Mod Connected: False
1: Display (selfie) mod: 0, HDMI: 0, Media Mod Connected: True
2: Display (selfie) mod: 0, HDMI: 1, Media Mod Connected: False
3: Display (selfie) mod: 0, HDMI: 1, Media Mod Connected: True
4: Display (selfie) mod: 1, HDMI: 0, Media Mod Connected: False
5: Display (selfie) mod: 1, HDMI: 0, Media Mod Connected: True
6: Display (selfie) mod: 1, HDMI: 1, Media Mod Connected: False
7: Display (selfie) mod: 1, HDMI: 1, Media Mod Connected: True
113 Turbo transfer Is Turbo Transfer active? boolean 0: False
1: True

Protobuf

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

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: Indicates command type (e.g. command, setting, query)
  2. Action: 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

Protobuf UUIDs

Below is a map of Protobuf Feature IDs and the characteristics used to write/notify. For additional details, see Services and Characteristics.

Feature Feature ID UUID Response UUID
Command 0xF1 GP-0072 GP-0073
Settings 0xF3 GP-0074 GP-0075
Query 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 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

Feature ID Action ID Response Action ID Description Request Response HERO10 Black HERO9 Black
0xF1 0x69 0xE9 Request set camera control status RequestSetCameraControlStatus ResponseGeneric >= v01.20.00
0x6B 0xEB Request set turbo active RequestSetTurboActive ResponseGeneric
0xF5 0x72 0xF2 Request get preset status RequestGetPresetStatus NotifyPresetStatus
0xF3 Async status update NotifyPresetStatus

Protobuf Command Details

Below are additional details about specific protobuf commands:

RequestSetCameraControlStatus

As part of the Global Behaviors feature, this command is used to tell the camera that the app (i.e. External Control) wants to be in control, which causes the camera to immediately exit any contextual menus and return to the idle screen.

Developers can query who is currently claiming control of the camera from camera status 114.

Developers can query whether the camera is currently in a contextual menu from camera status 63.

When the user interacts with the camera UI, the camera reclaims control and updates camera status to Control. When the user returns the camera UI to the idle screen, the camera updates camera status to Idle.

RequestSetTurboActive

Turbo Transfer Mode is a special feature that serves two purposes:

  • Temporarily modify low-level settings in the OS to prioritize WiFi offload speeds
  • Put up a UI on the camera indicating that media is being transferred and preventing the user from inadvertently changing settings or capturing new media

Developers can query whether the camera is currently in Turbo Transfer Mode from camera status 113.

While in Turbo Transfer Mode, if the user presses the Mode/Power or Shutter buttons on the camera, Turbo Transfer Mode will be deactivated.

Some cameras are already optimized for WiFi transfer and do not gain additional speed from this feature.

RequestGetPresetStatus

This command serves two purposes:

  • Describe which Preset Groups and Presets the camera supports in its 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/create/deleted)

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

Each Preset contains information about its ID, associated flatmode, 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 a list of settings associated with the Preset.

Preset Status should not be confused with camera status, which contains hundreds of camera/setting statuses on a system level.