Protocol specification

[scorpi11]

I used the source code of this cool project to collect information about the protocol. Now I can control JBL Flip 4 speakers in Linux and macOS. To contribute back to this project, I started to write a protocol description (mainly by copying the imported parts from the source code) and added some examples. Maybe someone is interested in this.

GATT characteristics to write control data:

0x000f (handle) or 65786365-6c70-6f69-6e74-2e636f6d0002 (UUID)

Data format:

byte 0|  byte 1   |    byte 2    |further bytes
 0xaa |packet type|payload length|   payload   

Byte 0 and 1 are mandatory. Depending on the packet type, there can be
a payload length + payload after this.

payload can be a parameter for the packet type (like SET_FEEDBACK_SOUNDS)
or a token with further parameters. Some tokens have an index byte before them.

Packet types:

ACK(0x00),

REQ_SPEAKER_INFO(0x11),
RES_SPEAKER_INFO(0x12),
SET_SPEAKER_INFO(0x15),

PLAY_SOUND(0x31),

REQ_DISCONNECT(0x35),

REQ_FIRMWARE_VERSION(0x41),
RES_FIRMWARE_VERSION(0x42),

REQ_DFU_START(0x43),
SET_DFU_DATA(0x44),
RES_DFU_STATUS_CHANGE(0x45),
REQ_DFU_CANCEL(0x47),

REQ_FEEDBACK_SOUNDS(0x65),
RES_FEEDBACK_SOUNDS(0x66),
SET_FEEDBACK_SOUNDS(0x67)
- playload 0x00 to disable
- playload 0x01 to enable

REQ_SPEAKERPHONE_MODE(0x68),
RES_SPEAKERPHONE_MODE(0x69),
SET_SPEAKERPHONE_MODE(0x70),

REQ_BASS_LEVEL(0x77),
RES_BASS_LEVEL(0x78),
SET_BASS_LEVEL(0x76),

REQ_ANALYTICS_DATA(0x81),
RES_ANALYTICS_DATA(0x82),

Tokens:

Tokens are part of the payload and can have parameters.

TOKEN_MAC(0x48),

TOKEN_AUDIO_SOURCE(0x47),

TOKEN_AUDIO_CHANNEL(0x46),
- index byte before token (0x00)
- 0x00 playload for mono
- 0x01 for left channel
- 0x02 for right channel

TOKEN_LINKED_DEVICE_COUNT(0x45),
TOKEN_BATTERY_STATUS(0x44),
TOKEN_COLOR(0x43):

            HwModel.CHARGE3 -> when (speakerColor) {
                0, 1 -> BLACK
                2 -> RED
                3 -> TEAL
                4 -> BLUE
                5 -> GRAY
                6 -> MOSAIC
                7 -> SQUAD
                8 -> ZAP
                9 -> MALTA
                else -> UNKNOWN
            }
            HwModel.FLIP3 -> when (speakerColor) {
                0, 1 -> BLACK
                2 -> RED
                3 -> ORANGE
                4 -> PINK
                5 -> GRAY
                6 -> BLUE
                7 -> YELLOW
                8 -> TEAL
                9 -> MALTA
                10 -> SQUAD
                11 -> ZAP
                12 -> TRIO
                13 -> MOSAIC
                else -> UNKNOWN
            }
            HwModel.FLIP4 -> when (speakerColor) {
                0, 1 -> BLACK
                2 -> RED
                3 -> BLUE
                4 -> TEAL
                5 -> GRAY
                6 -> WHITE
                7 -> MALTA
                8 -> SQUAD
                9 -> ZAP
                0x10 -> TRIO
                0x11 -> MOSAIC
                0x12 -> DARK_BLUE
                0x0A -> TRIO
                0x0B -> MOSAIC
                else -> UNKNOWN
            }
            HwModel.FLIP5 -> when (speakerColor) {
                0, 1 -> BLACK
                2 -> RED
                3 -> BLUE
                4 -> WHITE
                5 -> GREEN
                6 -> YELLOW
                7 -> GRAY
                8 -> DESERT
                9 -> TEAL
                0x10 -> PINK
                0x11 -> BLACKSTAR
                0x12 -> TOMORROWLAND
                0x13 -> SQUAD
                0x14 -> ECO_BLUE
                0x15 -> ECO_GREEN
                0x16 -> CAMO
                else -> UNKNOWN
            }
            HwModel.BOOMBOX -> when (speakerColor) {
                0, 1 -> BLACK
                2 -> GREEN
                8 -> SQUAD
                else -> UNKNOWN
            }
            HwModel.BOOMBOX2 -> when (speakerColor) {
                0, 1 -> BLACK
                8 -> SQUAD
                else -> UNKNOWN
            }
            HwModel.PULSE2 -> when (speakerColor) {
                0, 1 -> BLACK
                2 -> WHITE
                else -> UNKNOWN
            }
            HwModel.PULSE3 -> when (speakerColor) {
                0, 1 -> BLACK
                2 -> WHITE
                else -> UNKNOWN
            }
            HwModel.XTREME -> when (speakerColor) {
                0, 1 -> BLACK
                2 -> RED
                3, 6 -> BLUE
                4 -> SQUAD
                5 -> MALTA
                else -> UNKNOWN
            }
            HwModel.XTREME2 -> when (speakerColor) {
                0, 1 -> BLACK
                2 -> RED
                3 -> BLUE
                4 -> TEAL
                8 -> SQUAD
                0x12 -> GUN_METAL
                else -> UNKNOWN
            }
            HwModel.CHARGE4 -> when (speakerColor) {
                0, 1 -> BLACK
                2 -> RED
                3 -> BLUE
                4 -> WHITE
                5 -> GREEN
                6 -> YELLOW
                7 -> GRAY
                8 -> DESERT
                9 -> TEAL
                0x10 -> PINK
                0x11 -> SQUAD
                0x12 -> MAGENTA
                0x13 -> CAMO
                else -> UNKNOWN
            }
            HwModel.PULSE4 -> when (speakerColor) {
                0, 1 -> BLACK
                2 -> WHITE
                else -> UNKNOWN
            }
            HwModel.XTREME3 -> when (speakerColor) {
                0, 1 -> BLACK
                3 -> BLUE
                7 -> GRAY
                8 -> SQUAD
                else -> UNKNOWN
            }
            HwModel.CHARGE5 -> when (speakerColor) {
                1 -> BLACK
                2 -> RED
                3 -> BLUE
                4 -> WHITE
                5 -> GREEN
                7 -> GRAY
                9 -> TEAL
                0x10 -> PINK
                0x13 -> SQUAD
                else -> UNKNOWN
            }
            HwModel.PULSE5 -> when (speakerColor) {
                1 -> BLACK
                2 -> WHITE
                else -> UNKNOWN
            }
            HwModel.FLIP6 -> when (speakerColor) {
                1 -> BLACK
                2 -> RED
                3 -> BLUE
                4 -> WHITE
                5 -> GREEN
                6 -> YELLOW
                7 -> GRAY
                8 -> DESERT
                9 -> TEAL
                0x10 -> PINK
                0x11 -> BLACKSTAR
                0x12 -> TOMORROWLAND
                0x13 -> SQUAD
                0x14 -> ECO_BLUE
                0x15 -> ECO_GREEN
                0x16 -> CAMO
                else -> UNKNOWN
            }

TOKEN_MODEL(0x42),
        0x0023 /* CSR */ -> FLIP3
        0x0024 /* CSR */ -> XTREME
        0x0026 /* CSR */ -> PULSE2
        0x1EBC /* CSR */, 0x1F25 /* QCC - cancelled */ -> CHARGE3
        0x1ED1 /* CSR */, 0x1F24 /* QCC - cancelled */ -> FLIP4
        0x1ED2 /* CSR */, 0x1F28 /* QCC - cancelled */ -> PULSE3
        0x1EE7 /* CSR */, 0x1F27 /* QCC */ -> BOOMBOX
        0x1EFC /* CSR */, 0x1F26 /* QCC */, 0x2038 /* QCC - Gun Metal */ -> XTREME2
        0x1F17 /* CSR */, 0x1F29 /* QCC */ -> CHARGE4
        0x1F31 /* VIMICRO */ -> FLIP5
        0x1F53 /* VIMICRO */ -> BOOMBOX2
        0x1F56 /* VIMICRO */ -> PULSE4
        0x202F /* VIMICRO */ -> XTREME3
        0x2040 /* VIMICRO */ -> CHARGE5
        0x204FF /* VIMICRO */ -> FLIP6
        0x2050F /* VIMICRO */ -> PULSE5


TOKEN_NAME(0xC1);

Usage of certain packet types and tokens:

Request Speaker info (can be long, increase MTU if necessary)

0xaa11

Enable feedback sound:

0xaa670101

Play sound:

0xaa31

Use speaker for the left channel in connect+ mode:

aa1503004601

the first byte (0x00) after the payload (0x03) is some kind of index

Example commands for Linux:

Enable feedback sounds:

sudo gatttool -i hci0 -b <MAC address> --char-write-req -a 0x000f -n 0xaa670101

Play a sound:

sudo gatttool -i hci0 -b <MAC address> --char-write-req -a 0x000f -n 0xaa31

Set the speaker to play the left channel:

sudo gatttool -i hci0 -b <MAC address> --char-write-req -a 0x000f -n 0xaa1503004601

[1337vida]

Hey, this seems really cool! Do you have a way of contact so i can contact you privately?

[scorpi11]

Hi,

You can send an E-mail to tino at tikei.de

[EricAndrechek]

Hi @scorpi11 this is amazing stuff, thank you for documenting this! Is there any way you could help walk me through how I might run these commands on Mac? I am trying to use Bluetility to send and receive values but am having some trouble. Any insight you could offer is much appreciated!

[scorpi11]

I installed bleak via Homebrew and used it in Python scripts.

[XboxOneSogie720]

Are you able to read a characteristic using gatttool? I can't seem to get it to spit out any values from the speaker.

[scorpi11]

Yes, I use it like described in the examples. It seems to work better when no audio is playing. And the Connect+ mode has to be enabled by pressing the button on the speaker.

[XboxOneSogie720]

Oh hey, I actually discovered what I was doing wrong. I'm using LightBlue from the Mac app store to control mine, and I have to first subscribe to the read characteristic, then write to the write characteristic and the result shows up in the read characteristic. For me I didn't have to have Connect+ enabled. However, I was curious about getting the color info or name from the speaker, since whenever I tried specifying those tokens (based off how you did it to set the audio channel) it just responded with all of the speaker info. I'm guessing it just saw the packet to request speaker info and just gave me all of it. I tried this:

0xaa110143

aa because it's required
11 because that's to get speaker info
01 because one byte is being specified in the payload
43 because that's the token for color

Am I misunderstanding?