BLE Services

This page is intended for developers who are interested in communicating with a Circuit Playground Bluefruit from their own custom Bluetooth LE application. The source code for the firmware is available at this link:

All of the BLE services used by CPB's Bluefruit Playground firmware are documented below.

All Adafruit Service/Characteristic UUID128 share the same Base UUID :

  • ADAFxxxx-C332-42A8-93BD-25E905756CB8

Each service's UUID can be found by replacing xxxx with the service four-digit hex number.

Advertising

A device will advertise as a connectable type using the manufacturer specific data flag with Adafruit Company ID of 0x0822 as follows: 

| 1 byte     | 1 byte |  2 bytes | 1 byte   | 2 bytes | variable

-------------------------------------------------------------------------------------

| total len | Mfr Tag | 0x0822 | field len | field key | field value

There could be several of field (len, key, value) as long as they are all fitted into an advertising packet (31 byte for normal advertising, 200 bytes for extended advertising).

  • Total len : 1 + 2 + sum(field_len + 1)
  • Field len : 2 + len(field_value)
  • Field key is enumeration constant
    • 0x0000 :  Color ID, followed by 3 bytes of RGB for current color displayed on the board. Helpful to quickly know which board we are about to connect to.
    • 0x0001 : Board ID, followed by 2 bytes of USB PID of board. Can be used as a filter and display the board image on a mobile application
      • 0x8029: Feather nRF52840 Express (Arduino mode)
      • 0x802A: Feather nRF52840 Express (CircuitPython mode)
      • 0x8045: CPlayground Bluefruit (Arduino mode)
      • 0x8046: CPlayground Bluefruit (CircuitPython mode)
      • 0xEA60: Adafruit nRF52832 Feather (Arduino mode only)

Shared Characteristics

Measurement Period: 0001

  • { int32: period }
    • Read + Write
    • period = 1 to 2^31-1: Milliseconds between measurements
    • period = -1: Stop measuring
    • period = 0: Update the measurement whenever it changes, as often as possible

Service Version: 0002

  • { uint32: version }
    • Read
  • If characteristic is not present, version =  1 (v1)

Temperature Service

Temperature Service: 0100

  • Temperature: 0101
    • { float32: temperature }
      • Read + Notify
      • temperature in degrees Celsius
  • Measurement Period: 0001
  • Service Version: 0002 (optional): v1

Accelerometer Service

Accelerometer Service: 0200

  • Acceleration: 0201
    • ( float32: x, float32: y, float32: z }
      • Read + Notify
      • x, y, z acceleration values, in m/s^2
  • Measurement Period: 0001
  • Service Version: 0002 (optional): v1

Light Sensor Service

Light Sensor Service: 0300

  • Light Level: 0301
    • { level: float32 }
      • Read + Notify
  • Measurement Period: 0001
  • Service Version: 0002 (optional)

Button Status

Board Button Service: 0600

  • Pressed: 0601
    • {state: uint32}
      • Read + Notify
      • bit 0: slide switch: 1 for left, 0 for right
      • bit 1: 1 = button A pressed
      • bit 2: 1 = button B pressed
      • Other bits available for future buttons
  • Measurement Period: 0001
  • Service Version: 0002 (optional): v1

Tone Generator

Tone Service: 0C00

  • Tone: 0C01
    • { frequency: uint16, duration: uint32 }
      • Write
      • frequency: Hz, 0 for no tone (useful to turn off a non-stop tone)
      • duration: milliseconds, 0 for non-stop

NeoPixels

Addressable Pixel Service: 0900

  • General service for any kind of addressable pixels, including WS2812 (NeoPixel), WS2801, APA102 (DotStar), etc. It is the client’s responsibility to know the number of colors, color order, etc. and to fill the buffer appropriately. The server is only concerned with the electrical protocol.
  • Pixel Pin: 0901
    • { pin: uint8 }
      • Read + Write
      • pin: Send data out on this pin.
  • Pixel Pin Type: 0902
    • { type: uint8 }
      • Read + Write
      • 0 = WS2812 (NeoPixel), 800 kHz
      • 1 = SPI (APA102: DotStar)
      • [more protocols later]
  • Pixel Data: 0903
    • { start: uint16,  flags: uint8; data: uint8[up to 509] }
      • variable length
      • Write
      • index: start writing data into buffer at this byte number (byte, not pixel)
      • flags:
        • bit 0: 0 = don’t write to pixels yet
        • 1 = write entire buffer to pixels now
      • data: raw array of data for all pixels, in proper color order for type of pixel
  • Pixel Buffer Size: 0904
    • { length: uint16 }
      • Read + Write
      • Size of buffer, in bytes, needed to hold data for entire pixel string
This guide was first published on Dec 16, 2019. It was last updated on 2020-06-03 11:24:52 -0400.
This page (BLE Services) was last updated on Jun 03, 2020.