Nordic Thingy:52 for Web Bluetooth

About Thingy:52

The Nordic Thingy:52™ is a compact, power-optimized, multi-sensor development kit. It is an easy-to-use development platform, designed to help you build IoT prototypes and demos, without the need to build hardware or write firmware. Read more about it here.

This repository

This repository is an attempt to make it easier to start developing applications for Thingy:52 using Web Bluetooth. Web Bluetooth is a JavaScript API that makes it possible to communicate with Bluetooth Low Energy devices in web browsers. The implementation status for different browsers and platforms can be seen here. Just like the Web Bluetooth API, the methods in the Thingy object return promises.

This is work in progress, and for now this repository will help you connect to a Thingy:52 and access the following services and characteristics:

• Configuration

  • Name
  • Advertising parameters
  • Connection parameters
  • Eddystone URL
  • Cloud token
  • Firmware version
  • MTU request

• Environment

  • Configuration of sensors
  • Temperature
  • Pressure
  • Humidity
  • Gas sensor
  • Color sensor

• User interface

  • RGB LED
  • Button
  • External pins

• Motion

  • Configuration
  • Tap sensing
  • Step counter
  • Orientation
  • Quaternions
  • Euler angles
  • Rotation matrix
  • Heading
  • Gravity vector
  • Raw data

• Battery status

Get started

• Clone or download this repository, or just copy js/thingy.js into your own project.
• If you've used this repository, you can open index.html in a supported browser and open the console (ctrl + shift + J or cmd + alt + J).
• Turn on your Thingy:52.
• Create a new Thingy object and use the connect method to establish a BLE connection.
• You can now use the methods described in the documentation below to access sensor data.
• Note that Web Bluetooth requires connection requests to originate from a user action such as a click. From the console you can however call connect() directly.

Example

The following example will first connect to a thingy:52, then read its name and configure the RGB LED to "breathe" purple (color code 5, see here) pulses with 20% intensity and with 1500 ms delays between each pulse.

var thingy = new Thingy();
thingy.connect()
.then( () => {
    thingy.nameGet()
    .then( name => {
        console.log("This Thingy:52 is called " + name)
    })
    .then( () => { 
        thingy.ledSetBreathe(5, 20, 1500); 
    })
})
.catch( error => {
    console.log(error);
})

API documentation

Documentation is also available in HTML format here.

• Thingy
  • advParamsGet
  • advParamsSet
  • batteryLevelEnable
  • batteryLevelGet
  • buttonEnable
  • cloudTokenGet
  • cloudTokenSet
  • colorEnable
  • colorIntervalSet
  • colorSensorSet
  • connIntervalSet
  • connParamsGet
  • connSlaveLatencySet
  • connTimeoutSet
  • connect
  • disconnect
  • eddystoneGet
  • eddystoneSet
  • environmentConfigGet
  • eulerEnable
  • externalPinSet
  • externalPinsGet
  • firmwareVersionGet
  • gasEnable
  • gasModeSet
  • gravityVectorEnable
  • headingEnable
  • humidityEnable
  • humidityIntervalSet
  • ledGetStatus
  • ledSetBreathe
  • ledSetConstant
  • ledSetOneShot
  • magnetCompIntervalSet
  • motionConfigGet
  • motionConfigGet
  • motionProcessingFrequencySet
  • motionRawEnable
  • mtuGet
  • mtuSet
  • nameGet
  • nameGet
  • nameSet
  • orientationEnable
  • pressureEnable
  • pressureIntervalSet
  • quaternionEnable
  • readData
  • rotationMatrixEnable
  • stepCounterIntervalSet
  • stepEnable
  • tapEnable
  • temperatureCompIntervalSet
  • temperatureEnable
  • temperatureIntervalSet
  • wakeOnMotionSet
  • writeData

Thingy

Thingy:52 Web Bluetooth API.
BLE service details here

Parameters

• logEnabled bool Enables logging of all BLE actions. (optional, default true)

advParamsGet

Gets the current advertising parameters

Returns Promise<(Object | Error)> Returns an object with the advertising parameters when resolved or a promise with error on rejection.

advParamsSet

Sets the advertising parameters

Parameters

• interval string The advertising interval in milliseconds in the range of 20 ms to 5 000 ms.
• timeout string The advertising timeout in seconds in the range 1 s to 180 s.

Returns Promise<Error> Returns a promise.

batteryLevelEnable

Enables battery level notifications.

Parameters

• eventHandler function The callback function that is triggered on battery level change. Will receive a battery level object as argument.
• enable bool Enables notifications if true or disables them if set to false.

Returns Promise<Error> Returns a promise when resolved or a promise with an error on rejection

batteryLevelGet

Gets the battery level of Thingy.

Returns Promise<(number | Error)> Returns battery level in percentage when promise is resolved or an error if rejected.

buttonEnable

Enables button notifications from Thingy. The assigned event handler will be called when the button on the Thingy is pushed or released.

Parameters

• eventHandler function The callback function that is triggered on notification. Will receive a button object as argument.
• enable bool Enables notifications if true or disables them if set to false.

Returns Promise<Error> Returns a promise when resolved or a promise with an error on rejection.

cloudTokenGet

Gets the cloud token.

Returns Promise<(string | Error)> Returns a string with the cloud token when resolved or a promise with error on rejection.

cloudTokenSet

Sets the cloud token.

Parameters

• token string The cloud token to be stored.

Returns Promise<Error> Returns a promise.

colorEnable

Enables color sensor notifications from Thingy. The assigned event handler will be called when notifications are received.

Parameters

• eventHandler function The callback function that is triggered on notification. Will receive a color sensor object as argument.
• enable bool Enables notifications if true or disables them if set to false.

Returns Promise<Error> Returns a promise when resolved or a promise with an error on rejection

colorIntervalSet

Sets the color sensor update interval.

Parameters

• interval Number Step counter interval in milliseconds. Must be in the range 200 ms to 60 000 ms.

Returns Promise<Error> Returns a promise when resolved or a promise with an error on rejection.

colorSensorSet

Sets color sensor LED calibration parameters.

Parameters

• red Number The red intensity, ranging from 0 to 255.
• green Number The green intensity, ranging from 0 to 255.
• blue Number The blue intensity, ranging from 0 to 255.

Returns Promise<Error> Returns a promise when resolved or a promise with an error on rejection.

connIntervalSet

Sets the connection interval

Parameters

• minInterval string The minimum connection interval in milliseconds. Must be >= 7.5 ms.
• maxInterval string The maximum connection interval in milliseconds. Must be <= 4 000 ms.

Returns Promise<Error> Returns a promise.

connParamsGet

Gets the current connection parameters.

Returns Promise<(Object | Error)> Returns an object with the connection parameters when resolved or a promise with error on rejection.

connSlaveLatencySet

Sets the connection slave latency

Parameters

• slaveLatency string The desired slave latency in the range from 0 to 499 connection intervals.

Returns Promise<(Object | Error)> Returns a promise.

connTimeoutSet

Sets the connection supervision timeout Note: According to the Bluetooth Low Energy specification, the supervision timeout in milliseconds must be greater than (1 + slaveLatency) _ maxConnInterval _ 2, where maxConnInterval is also given in milliseconds.

Parameters

• timeout string The desired connection supervision timeout in milliseconds and in the rango of 100 ms to 32 000 ms.

Returns Promise<Error> Returns a promise.

connect

Connects to Thingy. The function stores all discovered services and characteristics to the Thingy object.

Returns Promise<Error> Returns an empty promise when resolved or a promise with error on rejection

disconnect

Method to disconnect from Thingy.

Returns Promise<Error> Returns an empty promise when resolved or a promise with error on rejection.

eddystoneGet

Gets the configured Eddystone URL

Returns Promise<(string | Error)> Returns a string with the URL when resolved or a promise with error on rejection.

eddystoneSet

Sets the Eddystone URL

Parameters

• prefix number Code for prefix, according to specification.
• url string The URL.
• postfix number Optional code for postfix according to specification. (optional, default null)

Returns Promise<Error> Returns a promise.

environmentConfigGet

Gets the current configuration of the Thingy environment module.

Returns Promise<(Object | Error)> Returns an environment configuration object when promise resolves, or an error if rejected.

eulerEnable

Enables Euler angle data notifications from Thingy. The assigned event handler will be called when notifications are received.

Parameters

• eventHandler function The callback function that is triggered on notification. Will receive an Euler angle data object as argument.
• enable bool Enables notifications if true or disables them if set to false.

Returns Promise<Error> Returns a promise when resolved or a promise with an error on rejection

externalPinSet

Set an external pin to chosen state.

Parameters

• pin Determines which pin is set. Range 1 - 4.
• value Sets the value of the pin. 0 = OFF, 255 = ON.

Returns Promise<Error> Returns a promise when resolved or a promise with an error on rejection.

externalPinsGet

Gets the current external pin settings from the Thingy device. Returns an object with pin status information.

Returns Promise<(Object | Error)> Returns an external pin status object.

firmwareVersionGet

Gets the current firmware version.

Returns Promise<(string | Error)> Returns a string with the firmware version or a promise with error on rejection.

gasEnable

Enables gas notifications from Thingy. The assigned event handler will be called when notifications are received.

Parameters

• eventHandler function The callback function that is triggered on notification. Will receive a gas object as argument.
• enable bool Enables notifications if true or disables them if set to false.

Returns Promise<Error> Returns a promise when resolved or a promise with an error on rejection

gasModeSet

Sets the gas mode.

Parameters

• mode Number 1 = 1 s update interval, 2 = 10 s update interval, 3 = 60 s update interval.

Returns Promise<Error> Returns a promise when resolved or a promise with an error on rejection.

gravityVectorEnable

Enables gravity vector notifications from Thingy. The assigned event handler will be called when notifications are received.

Parameters

• eventHandler function The callback function that is triggered on notification. Will receive a heading object as argument.
• enable bool Enables notifications if true or disables them if set to false.

Returns Promise<Error> Returns a promise when resolved or a promise with an error on rejection

headingEnable

Enables heading notifications from Thingy. The assigned event handler will be called when notifications are received.

Parameters

• eventHandler function The callback function that is triggered on notification. Will receive a heading object as argument.
• enable bool Enables notifications if true or disables them if set to false.

Returns Promise<Error> Returns a promise when resolved or a promise with an error on rejection

humidityEnable

Enables humidity notifications from Thingy. The assigned event handler will be called when notifications are received.

Parameters

• eventHandler function The callback function that is triggered on notification. Will receive a humidity object as argument.
• enable bool Enables notifications if true or disables them if set to false.

Returns Promise<Error> Returns a promise when resolved or a promise with an error on rejection

humidityIntervalSet

Sets the humidity measurement update interval.

Parameters

• interval Number Step counter interval in milliseconds. Must be in the range 100 ms to 60 000 ms.

Returns Promise<Error> Returns a promise when resolved or a promise with an error on rejection.

ledGetStatus

Gets the current LED settings from the Thingy device. Returns an object with structure that depends on the settings.

Returns Promise<Object> Returns a LED status object. The content and structure depends on the current mode.

ledSetBreathe

Sets the LED in "breathe" mode where the LED pulses with the specified color, intensity and delay between pulses.

Parameters

• color The color code. 1 = red, 2 = green, 3 = yellow, 4 = blue, 5 = purple, 6 = cyan, 7 = white.
• intensity Intensity of LED pulses. Range from 0 to 100 [%].
• delay Delay between pulses in milliseconds. Range from 50 ms to 10 000 ms.

Returns Promise<Error> Returns a resolved promise or an error in a rejected promise.

ledSetConstant

Sets the LED in constant mode with the specified RGB color.

Parameters

• red The value for red color in an RGB color. Ranges from 0 to 255.
• green The value for green color in an RGB color. Ranges from 0 to 255.
• blue The value for blue color in an RGB color. Ranges from 0 to 255.

Returns Promise<Error> Returns a resolved promise or an error in a rejected promise.

ledSetOneShot

Sets the LED in one-shot mode

Parameters

• color The color code. 1 = red, 2 = green, 3 = yellow, 4 = blue, 5 = purple, 6 = cyan, 7 = white.
• intensity Intensity of LED pulses. Range from 0 to 100 [%].

Returns Promise<Error> Returns a resolved promise or an error in a rejected promise.

magnetCompIntervalSet

Sets the magnetometer compensation interval.

Parameters

• interval Number Magnetometer compensation interval in milliseconds. Must be in the range 100 ms to 1 000 ms.

Returns Promise<Error> Returns a promise when resolved or a promise with an error on rejection.

motionConfigGet

Gets the current configuration of the Thingy motion module.

Returns Promise<(Object | Error)> Returns a motion configuration object when promise resolves, or an error if rejected.

motionConfigGet

Motion service

motionProcessingFrequencySet

Sets motion processing unit update frequency.

Parameters

• frequency Number Motion processing frequency in Hz. The allowed range is 5 - 200 Hz.

Returns Promise<Error> Returns a promise when resolved or a promise with an error on rejection.

motionRawEnable

Enables raw motion data notifications from Thingy. The assigned event handler will be called when notifications are received.

Parameters

• eventHandler function The callback function that is triggered on notification. Will receive a raw motion data object as argument.
• enable bool Enables notifications if true or disables them if set to false.

Returns Promise<Error> Returns a promise when resolved or a promise with an error on rejection

mtuGet

Gets the current Maximal Transmission Unit (MTU)

Returns Promise<(number | Error)> Returns the MTU when resolved or a promise with error on rejection.

mtuSet

Sets the current Maximal Transmission Unit (MTU)

Parameters

• mtuSize number The desired MTU size.
• peripheralRequest bool Optional. Set to true if peripheral should send an MTU exchange request. Default is false; (optional, default false)

Returns Promise<Error> Returns a promise.

nameGet

Gets the name of the Thingy device.

Returns Promise<(string | Error)> Returns a string with the name when resolved or a promise with error on rejection.

nameGet

Configuration service

nameSet

Sets the name of the Thingy device.

Parameters

• name string The name that will be given to the Thingy.

Returns Promise<Error> Returns a promise.

orientationEnable

Enables orientation detection notifications from Thingy. The assigned event handler will be called when notifications are received.

Parameters

• eventHandler function The callback function that is triggered on notification. Will receive a orientation detection object as argument.
• enable bool Enables notifications if true or disables them if set to false.

Returns Promise<Error> Returns a promise when resolved or a promise with an error on rejection

pressureEnable

Enables pressure notifications from Thingy. The assigned event handler will be called when notifications are received.

Parameters

• eventHandler function The callback function that is triggered on notification. Will receive a pressure object as argument.
• enable bool Enables notifications if true or disables them if set to false.

Returns Promise<Error> Returns a promise when resolved or a promise with an error on rejection

pressureIntervalSet

Sets the pressure measurement update interval.

Parameters

• interval Number Step counter interval in milliseconds. Must be in the range 50 ms to 60 000 ms.

Returns Promise<Error> Returns a promise when resolved or a promise with an error on rejection.

quaternionEnable

Enables quaternion notifications from Thingy. The assigned event handler will be called when notifications are received.

Parameters

• eventHandler function The callback function that is triggered on notification. Will receive a quaternion object as argument.
• enable bool Enables notifications if true or disables them if set to false.

Returns Promise<Error> Returns a promise when resolved or a promise with an error on rejection

readData

Method to read data from a Web Bluetooth characteristic. Implements a simple solution to avoid starting new GATT requests while another is pending. Any attempt to read while another GATT operation is in progress, will result in a rejected promise.

Parameters

• characteristic Object Web Bluetooth characteristic object

Returns Promise<(Uint8Array | Error)> Returns Uint8Array when resolved or an error when rejected

rotationMatrixEnable

Enables rotation matrix notifications from Thingy. The assigned event handler will be called when notifications are received.

Parameters

• eventHandler function The callback function that is triggered on notification. Will receive an rotation matrix object as argument.
• enable bool Enables notifications if true or disables them if set to false.

Returns Promise<Error> Returns a promise when resolved or a promise with an error on rejection

stepCounterIntervalSet

Sets the step counter interval.

Parameters

• interval Number Step counter interval in milliseconds. Must be in the range 100 ms to 5 000 ms.

Returns Promise<Error> Returns a promise when resolved or a promise with an error on rejection.

stepEnable

Enables step counter notifications from Thingy. The assigned event handler will be called when notifications are received.

Parameters

• eventHandler function The callback function that is triggered on notification. Will receive a step counter object as argument.
• enable bool Enables notifications if true or disables them if set to false.

Returns Promise<Error> Returns a promise when resolved or a promise with an error on rejection

tapEnable

Enables tap detection notifications from Thingy. The assigned event handler will be called when notifications are received.

Parameters

• eventHandler callback The callback function that is triggered on notification. Will receive a tap detection object as argument.
• enable bool Enables notifications if true or disables them if set to false.

Returns Promise<Error> Returns a promise when resolved or a promise with an error on rejection

temperatureCompIntervalSet

Sets the temperature compensation interval.

Parameters

• interval Number Temperature compensation interval in milliseconds. Must be in the range 100 ms to 5 000 ms.

Returns Promise<Error> Returns a promise when resolved or a promise with an error on rejection.

temperatureEnable

Enables temperature notifications from Thingy. The assigned event handler will be called when notifications are received.

Parameters

• eventHandler function The callback function that is triggered on notification. Will receive a temperature object as argument.
• enable bool Enables notifications if true or disables them if set to false.

Returns Promise<Error> Returns a promise when resolved or a promise with an error on rejection

temperatureIntervalSet

Sets the temperature measurement update interval.

Parameters

• interval Number Step counter interval in milliseconds. Must be in the range 100 ms to 60 000 ms.

Returns Promise<Error> Returns a promise when resolved or a promise with an error on rejection.

wakeOnMotionSet

Sets wake-on-motion feature to enabled or disabled state.

Parameters

• enable bool Set to True to enable or False to disable wake-on-motion feature.

Returns Promise<Error> Returns a promise when resolved or a promise with an error on rejection.

writeData

Method to write data to a Web Bluetooth characteristic. Implements a simple solution to avoid starting new GATT requests while another is pending. Any attempt to send data during another GATT operation will result in a rejected promise. No retransmission is implemented at this level.

Parameters

• characteristic Object Web Bluetooth characteristic object
• dataArray Uint8Array Typed array of bytes to send

Returns Promise