BlueSee

Contents

• Global Properties
• Requirements
• Functions
• Class bluesee.Span
• Class bluesee.UUID
• Class bluesee.Data
• Class bluesee.Characteristic
• Class Widget
• Label Widget
• HEX Widget
• Switch Widget
• Option Widget
• Button Widget
• Textfield Widget
• Demo Script

Module

• BlueSee

Module BlueSee

...a Bluetooth Low Energy Debugging Toolkit

“Bluetooth Smart”, “Bluetooth Low Energy”, these are phrases that have become increasingly common in recent years.

Anyone working in a technology field has probably used, or at least encountered, BLE technology in their day-to-day life. Whether wireless beacons that provide additional wireless functionality, wearable fitness devices, smartwatches, or ‘smart lock’ technology, BLE surrounds us.

Obviously, it becomes useful to be able to explore the BLE environment around you, or to be able to debug your own BLE-enabled peripherals.

BlueSee aims to address this need; it provides a simple way to examine the peripherals which are advertising around you, to connect to them, and explore the services they expose.

It also provides a simple method for extending BlueSee’s capabilities to custom BLE protocols, using the Lua scripting language.

BlueSee is meant primarily for hardware developers who need a quick way to interact with prototype devices for testing. However, it is also a useful tool for those who are merely curious about what their local BLE environment is like. There are a great many interesting things chattering between each other to be found in the average office or home, after all!

Info:

• Copyright: Synapse Product Development, Inc. 2017
• Author: Jake, Rachel, Nate, Jordan, Gabe

Global Properties

Requirements

Functions

Class bluesee.Span

Class bluesee.UUID

Class bluesee.Data

Class bluesee.Characteristic

Class Widget

Label Widget

HEX Widget

Switch Widget

Option Widget

Button Widget

Textfield Widget

Demo Script

Global Properties

precedence

The precedence value for registering span init functions.

Fields:

• weight_fallback 1
• weight_normal 10
• weight_override 100

Usage:

bluesee.register_service(uuid, callback, bluesee.weight_override)

parsers

Advertisement parser types for bluesee.set_adv_parser.

Fields:

• adv_srv_uuid 0
• adv_mfg_cic 1

Usage:

bluesee.set_adv_parser(bluesee.adv_mfg_cic, value, callback)

categories

Category values for registering span init functions

Fields:

• barcode "barcode"
• ble "bluetooth"
• device "device information"
• fitness "fitness"
• fitness_cycling "fitness - cycling"
• fitness_weights "fitness - weights"
• fitness_running "fitness - running"
• glasses "glasses"
• gps "gps"
• health "health"
• location "location"
• music "music"
• phone "phone"
• power "power"
• remote "remote"
• tag "tag"
• time "time"
• ui "ui"
• unknown "unknown"

Usage:

bluesee.set_display_category(uuid, bluesee.fitness_cycling)

widgets

Widget types for use in service panels

Fields:

• label "label"
• hex "hex"
• textfield "textfield"
• switch "switch"
• option "option"
• button "button"
• hr "hr"

Usage:

local control = bluesee.new_widget(bluesee.button)

Requirements

bluesee.register_service (uuid, callback[, options])

Registers a service panel initialization callback function against the given service UUID. The given function will be called when the user connects to a device, after the service and its characteristics have been discovered.

If multiple service panel initialization functions are registered for a UUID with the same options, the most recently registered panel will be used.

Parameters:

• uuid bluesee.UUID the UUID of the service. Can be nil, in which case the initialization callback will be registered for all services.
• callback function The callback function takes a single argument, a newly instantiated Service Panel object. A service callback will typically create the needed widgets to compose the display of the service, and register for updates and notifications from those characteristics.
• options table can be one of precedence value (optional)

Functions

bluesee.api_version ()

Returns the current version of the BlueSee lua API. Used to compare BlueSee package (.blpkg) versions for compatibility with the current version of the BlueSee API.

bluesee.set_default_service (callback)

Registers a default service panel initialization callback function. This allows for the creation of a default Service Panel for unknown services.

Parameters:

• callback function a function that takes a single argument, a newly instantiated Service Panel object. It is recommended that a default UI, composed of BlueSee widgets, is added to the returned service panel.

bluesee.set_adv_parser (parser, uuid, callback)

Sets the advertisement data parser that will be called when BlueSee receives an advertisement that passes the given filter. When an advertisement packet is received, BlueSee will attempt to find a registered advertisement data parser callback that matches the service uuid in the order of the filters. The first callback found will be called and the process terminated unless nil is returned. The provided callback must return a string which will be displayed instead of the raw advertisement data for the device.

Parameters:

• parser parsers the parser type
• uuid bluesee.UUID the uuid of the service
• callback function takes three parameters:

  uuid: a UUID object representing the service uuid

  name: the advertised name of the device (string)

  data: the manufacturer data as a bluesee.Data object

bluesee.set_adv_parser (parser, cic, callback)

Sets the advertisement data parser that will be called when BlueSee receives an advertisement that passes the given filter. When an advertisement packet is received, BlueSee will attempt to find a registered advertisement data parser callback in the order of the filters. The first callback found that matches the Company Identifier Code will be called and the process terminated unless nil is returned. The provided callback must return a string which will be displayed instead of the raw advertisement data for the device.

Parameters:

• parser parsers the parser type
• cic integer the Company Identifier Code
• callback function takes three parameters:

  cic: an integer representing the Company Identifier Code

  name: the advertised name of the device (string)

  data: the manufacturer data as a bluesee.Data object

bluesee.set_display_name (uuid, name)

Set a display name (e.g. “MyService”) for the given service UUID. The primary purpose of this function is clearly separate a custom device from a potentially large field of devices whose service names may not be known. If a display name is not set for a service UUID, an attempt will be made to reconcile the service UUID with a service defined by the Bluetooth SIG. If no service name is supplied or found, the UUID itself will be displayed in the service panel and elsewhere.

Parameters:

• uuid bluesee.UUID the service uuid for which the display is being set
• name string the display name of the service

bluesee.set_display_category (uuid, category)

Sets the category for the given service uuid, rather than showing the ?
icon for an unknown or uncategorized service. If a category name is not supplied for a custom services, an attempt will be made to locate the category of the given service in the Bluetooth SIG service definitions. The category name will determine the icon used for the service.

Parameters:

• uuid bluesee.UUID the uuid of the service
• category categories the display name of the category for the service

bluesee.new_widget (type)

Returns a new widget of the given type.

Parameters:

• type widgets the desired type of widget.

bluesee.new_data (string)

Returns a data object created from the passed raw binary string.

Parameters:

• string string a raw binary string

Class bluesee.Span

bluesee.Span.uuid

The BLE service UUID the service panel represents.

Usage:

span:log("This service panel represents the " .. span.uuid .. " service")

bluesee.Span:on_service_discovered ()

BlueSee will call this function when the service is discovered. The function takes no arguments.

bluesee.Span:on_ch_discovered (a)

BlueSee will evoke this callback for each characteristic of the service, in order, when discovery is complete. If desired, the user can create a widget to represent the characteristic and register it with the panel. This callback will have a single argument, a bluesee.Characteristic object representing the characteristic that was discovered.

Parameters:

• a function function that takes no arguments.

bluesee.Span:on_discovery_complete ()

BlueSee will call this function after on_ch_discovered() has been called for all discovered characteristics.

bluesee.Span:add_widget (widget)

Adds the given widget to the panel. If the given widget is nil, does nothing.

Parameters:

• widget widgets

bluesee.Span:ch_get (uuid)

Returns the bluesee.Characteristic object representing the characteristic of the service with the given UUID, or nil if no such characteristic has been discovered.

Parameters:

• uuid bluesee.UUID

bluesee.Span:log (text)

Logs the given text to the panel’s log tab.

Parameters:

• text string

Class bluesee.UUID

bluesee.UUID.new (value[, width])

A new BlueSee.UUID is constructed from the given 16-bit or 32-bit value.
If the width is not specified, the smallest width that can represent the given value is used.

Parameters:

• value integer uuid as a a 16 bit or 32 bit value
• width integer if specified, must be 16 or 32 (other values will generate an error). (optional)

bluesee.UUID.new (data)

A new bluesee.UUID is constructed from the given bluesee.Data object.
If the length of the data object is not 2 (16 bits), 4 (32 bits), or 16 (128 bits), an error will be generated.

Parameters:

• data bluesee.Data the data object to contstruct the uuid from.

bluesee.UUID:unsigned_integer ()

The UUID is returned as an integer. If it’s not a 16 or 32-bit UUID, an error is generated.

Returns:

integer the integer value of the uuid

bluesee.UUID:data ()

Returns a bluesee.Data representation of the UUID.

bluesee.UUID.new (string)

A new bluesee.UUID is constructed from the given string, which can take one the following forms:

'xxxxxxxx-xxxx-xxxx-xxxx-xxxx' 'xxxxxxxxxxxxxxxxxxxxxxxx'

'xxxxxxxx'

'xxxx'

All forms are case-insensitive.

Parameters:

• string string uuid as a string

bluesee.UUID:tostring ()

Provides a string representation of the UUID.

Returns:

string If the length of the data is 2, a string with format "%02X%02X" with respective bytes at indices 0 and 1 will be returned. If the length is 16, a string representation of the uuid will be returned. Othewise, returns nil.

bluesee.UUID:length ()

Provides the length of the uuid's data object.

Returns:

integer the length.

Class bluesee.Data

bluesee.Data.endian_little

The default byte order.

Usage:

local data = bluesee.Data.new(2, 1, bluesee.Data.endian_little)

bluesee.Data.endian_big

Represents big endianness.

Usage:

local data = bluesee.Data.new(, 1, bluesee.Data.endian_big)

bluesee.Data.new (n)

Creates a new bluesee.Data object with space for n bytes (must be greater than zero). Each byte will be initialized to zero.

Parameters:

• n the amount of space to initialize the object with. must be greater than zero.

Returns:

a bluesee.Data object initialized with space for n bytes.

bluesee.Data.new (value, width[, endianness])

Creates a new bluesee.Data object initialized with an integer value. If the given value does not fit into the width specified, it will be truncated bit-wise.

Parameters:

• value the integer value.
• width bytes, must be 1, 2, 4, or 8 - any other values will generate an error.
• endianness byte order, specified as bluesee.Data.endianlittle (the default), or bluesee.Data.endianbig. (optional)

Returns:

a bluesee.Data data

bluesee.Data.new (table)

Creates a new bluesee.Data object initialized with a table of integer values. If the table contains any non-integer entries, an error will be generated. By default, the values must be unsigned bytes (0–255).

Parameters:

• table the table of integer values. Each value must be unsigned bytes (0-255).

Returns:

a bluesee.Data object initialized with the given table of integer values.

bluesee.Data.new (string)

Creates a new bluesee.Data object with a string. For example, bluesee.Data.new(‘0xb10b’).

Parameters:

• string an ASCII-encoded string of hexadecimal bytes.

Returns:

a bluesee.Data object

bluesee.Data.new_from_binary (binary)

Creates a new bluesee.Data object from a binary Lua blob (string).

Parameters:

• binary string (Lua blob).

Returns:

a bluesee.Data object

bluesee.Data:as_string ()

Returns a Lua string representation of the data.

Returns:

string a Lua string. If the Lua string from bluesee.Data object is nil, a hex string will be returned.

bluesee.Data:tostring ()

Returns the data object as a hexadecimal string.

Returns:

string The hexadecimal representation of the data object.

bluesee.Data:length ()

Returns the length of the data object.

Returns:

integer the lenght of the data object.

bluesee.Data:sub (n, i)

Returns a new bluesee.Data object containing a copy of the n bytes starting at byte i (1-indexed).

Parameters:

• n integer the length of the range
• i integer the position at which to begin the range (1-indexed).

Returns:

bluesee.Data the new data object constructed from the given range.

bluesee.Data:as_raw_string ()

Returns a raw representation of the data.

Returns:

string a Lua string.

bluesee.Data:as_hex_string ()

Returns a hexadecimal representation of the data.

Returns:

string

bluesee.Data:unsigned_integer ([endianness])

Returns an unsigned integer interpretation of the data. The length of the data must be 1, 2, 4, or 8 (otherwise an error will be generated).

Parameters:

• endianness integer Byte order is specified as BlueSee.Data.endian_little, or BlueSee.Data.endian_big. The default is BlueSee.Data.endian_little. (optional)

Returns:

integer

bluesee.Data:signed_integer ([endianness])

Returns a signed integer interpretation of the data. The length of the data must be 1, 2, 4, or 8 (otherwise an error will be generated).

Parameters:

• endianness integer Byte order is specified as BlueSee.Data.endian_little, or bluesee.Data.endian_big. The default is bluesee.Data.endian_little. (optional)

Returns:

integer

bluesee.Data:set (i, n, value[, endianness])

Sets a field of width n starting at byte i (1-indexed) to the given value.

Parameters:

• i integer the starting byte.
• n integer the width, must be 1, 2, 4, or 8 (otherwise an error will be generated).
• value integer must be between 0 and 255
• endianness integer Byte order is specified as bluesee.Data.endian_little, or bluesee.Data.endian_big. The default is bluesee.Data.endian_little. (optional)

Class bluesee.Characteristic

bluesee.Characteristic.uuid

The bluesee.UUID of the characteristic, read-only

Usage:

if (ch.uuid == my_custom_uuid) then control.title = ch.value

bluesee.Characteristic.service_uuid

The UUID of the service this instance is a part of

bluesee.Characteristic.readable

true if the characteristic is readable

bluesee.Characteristic.writeable

true if the characteristic is writeable

bluesee.Characteristic.subscribable

true if the characteristic provides notifications

ch:subscribe (callback)

Subscribes for notifications from the characteristic. The given callback function will be called whenever a notification is received. More than one callback can be subscribed to a characteristic.

Parameters:

• callback function , a function that takes takes one argument, the bluesee.Characteristic that was notified.

ch:unsubscribe (callback)

Unsubscribes for notifications from the characteristic. If no more callbacks are registered, completely unsubscribes.

Parameters:

• callback function , a function that takes takes one argument, the bluesee.Characteristic that was unsubscribed from.

ch:add_read_callback (callback)

Registers a callback function that will be called whenever a read returns for the characteristic.

Parameters:

• callback function , a function that takes takes one argument, the bluesee.Characteristic that was unsubscribed from.

ch:read ()

Initiates a read of the characteristic. When the read returns, the last read value is updated and any registered callbacks are called.

ch:write (string)

Writes the given value to the characteristic.

Parameters:

• string string , a hexadecimal string

ch:write (data)

Writes the given data to the characteristic.

Parameters:

• data bluesee.Data , the data object to write

ch:write (a)

Writes the given table of values to the characteristic.

Parameters:

• a table table whose values must each be between 0 and 255.

ch:write (value, width, byte_order)

Writes the given value to the characteristic.
Sets a field of width n starting at byte i (1-indexed) to the given value.

Parameters:

• value , a hexadecimal string, bluesee.Data, or table. If not given, the the smallest width that can represent the given value is used.
• width integer must be 1, 2, 4, or 8 (otherwise an error will be generated).
• byte_order integer Byte order is specified as bluesee.Data.endian_little, or bluesee.Data.endian_big.
  The default is bluesee.Data.endian_little.

ch:write_binary (string)

Writes the given value to the characteristic.

Parameters:

• string string, can be either a Lua binary blob or a bluesee.Data object.

ch:value ()

Returns the last-read value for the given characteristic (doesn’t actually perform a read).

Returns:

bluesee.Data value a bluesee.Data object, or nil if a GATT read or notify has not yet completed.

ch:unsigned_integer (endianness)

Returns an unsigned integer interpretation of the characteristic value.

Parameters:

• endianness bluesee.Data.endianness

ch:signed_integer (endianness)

Returns a signed integer interpretation of the characteristic value.

Parameters:

• endianness bluesee.Data.endianness

Class Widget

Usage:

local my_widget = bluesee.new_widget(bluesee.button)
span:add_widget(my_widget)

Widget.type

The type of the widget (see above list of available widget types), read-only.

Widget.title

The string designed to be the “key”, identifying what the widget’s value actually entails, read-write.

widget.on_fetch (callback)

If set, the provided function will be called when widgets are told to fetch new data. This function is called when a read has been triggered or the Span has been told to refresh.

Parameters:

• callback function This function will receive no parameters. This is accessible by the on_fetch property on the widget, but only for setting; due to the way the Lua function gets encapsulated, you cannot retrieve it from the Lua side.

widget.on_refresh (callback)

If set, the provided function to be performed by this widget when widgets are told to refresh themselves, such as during a toggle event (switch widget). The provided function will receive no parameters. This is accessible by the on_refresh property on the widget, but only for setting; due to the way the Lua function gets encapsulated, you cannot retrieve it from the Lua side.

Parameters:

• callback function This function will receive no parameters. This is accessible by the on_fetch property on the widget, but only for setting; due to the way the Lua function gets encapsulated, you cannot retrieve it from the Lua side.

Label Widget

value

The value of the property identified by the title property, as a string. read, write.

HEX Widget

read_only

(boolean) (read, write). This toggles whether or not this hex component is read-only. A read-only component disables the ‘write’ button by default, and will not accept text input in the box.

readable

(boolean) (read, write). This toggles whether or not this hex widget should have the ‘read’ button enabled or not. If set to false, the ‘read’ button will be disabled. Setting this to false and setting the component readonly will disable all interaction, making it only valid for display. If the read button is clicked, the standard component onfetch handler will be called.

bin_value

(read, write). This will retrieve the binary value as a bluesee.Data object, (not a Lua binary string value).

text_value

(read, write). This will retrieve the current value as a hexadecimal string.

can_subscribe

(boolean) (read, write). Informs the widget that the characteristic it is representing can be subscribed to, allowing the widget to expose subscription controls, such as a button for toggling subscription state.

is_subscribed

(boolean). Informs the widget that the characteristic it is representing has been subscribed to or unsubscribed from, giving the widget an opportunity to update its UI. When the widget is refreshed by the Span it will check this flag in order to display the correct UI. If set to false, the widget will display a control to subscribe to the characteristic it represents. If set to true, the widget will display a control unsubscribe from the characteristic it represents.

hex.on_enter (callback)

This sets a Lua function to be executed when the user presses enter in the text input field or clicks the ‘write’ button, if the control is not set read-only.

Parameters:

• callback function a function that receives no parameters.

hex.toggle_subscription (callback)

If the characteristic can be subscribed to (can_subscribe), this function registers a callback that will be called by a subscription toggle control, such as a button. Typically, registering this callback will mean that ch:subscribe(function) or ch:unsubscribe(function) are invoked on the characteristic the widget is representing.

Parameters:

• callback function a function that receives no parameters.

hex.auto_subscribe ()

Provides the widget with a user-set flag (from within the BlueSee application’s settings) telling the widget whether it should automatically subscribe to a characteristic, if applicable. If the flag has been set to true and the characteristic can be subscribed to, the widget should call ch:subscribe(fn), subscribing to the characteristic. If the flag has been set to false, the widget should register the toggle_subscription callback in order change subscription state for the characteristic.

Returns:

boolean flag, whether the auto_subscribe hook has been set by the user.

Usage:

if hex.auto_subscribe then
    ch:subscribe(subscribe_callback)
end

Switch Widget

enabled

(boolean) (read, write). Sets or gets whether or not the switch is presently toggled on.

switch.on_toggle (callback)

Sets a callback to be called whenever the switch is toggled on or off.

Parameters:

• callback function a function that receives no parameters.

Option Widget

enabled

(boolean) (read, write). This toggles whether or not the combobox is interactive, or if it is greyed out.

selected_option

(string) (read-only). The string ‘value’ of the current selected option.

selected_index

(integer) (read, write). An integer representing which option is currently selected. Per Lua, this is a 1-based index.

option.on_click (callback)

Sets a callback to be called when the option value changes.

Parameters:

• callback function a function that receives no parameters.

option:add_option (label, value)

Adds a new option to the combobox.

Parameters:

• label string , will be displayed to the user.
• value string , what is offered to the script.

Button Widget

enabled

(boolean). Sets whether or not this button is enabled and clickable, or greyed out and disabled.

option.on_click (callback)

Sets a callback to be called when the button is clicked.

Parameters:

• callback function a function that receives no parameters.

Textfield Widget

value

(string) (read, write). The value of the textfield.

textfield.on_value_update (callback)

Registers a callback that can receive value updates, providing “on change” style event handling of user input.

Parameters:

• callback function a function that takes a single argument, the string value stored internally by the widget.

Demo Script

synbulb.blua

This script demonstrates scripted service registration, working with bluesee.* classes (Data, UUID, etc.), and adding widgets and callbacks.

Usage:

local bluesee = require "bluesee"

-- define the service
local synbulb_service_uuid = bluesee.UUID.new('94e395bc-0ef8-4830-850d-9d16e485bcf0')
bluesee.set_display_name(synbulb_service_uuid, 'Synapse Connected Lightbulb')
bluesee.set_display_category(synbulb_service_uuid, bluesee.ui)

-- define characteristics
local light_uuid = bluesee.UUID.new('98aaf60d-4171-46f3-b79a-1922da67d0cc')
local morse_uuid = bluesee.UUID.new('36614ba0-ef61-4d1d-9e8b-3bc9c6271e59')

-- Register the service
bluesee.register_service(synbulb_service_uuid, function(span)

    -- Create a label widget
    local bulb_label = bluesee.new_widget(bluesee.label)
    bulb_label.title = "Current Bulb Value"
    bulb_label.value = "(unknown)"

    -- Add the label widget to the service panel
    span:add_widget(bulb_label)

    -- Add a divider
    span:add_widget(bluesee.new_widget(bluesee.hr))

    local morse_input = bluesee.new_widget(bluesee.textfield)
    morse_input.title = "Morse Code Message"
    morse_input.value = ""

    -- Add the user input widget to the service panel
    span:add_widget(morse_input)

    local morse_ch = nil

    local morse_button = bluesee.new_widget(bluesee.button)
    morse_button.title = "Play Message"

    -- Define the click handler for the button widget
    morse_button.on_click = function()
        if morse_ch ~= nil then
            morse_ch:write_binary(morse_input.value)
        end
    end

    -- Add the button widget to the service panel
    span:add_widget(morse_button)

    -- Define characteristic discovery callback
    span.on_ch_discovered = function(ch)

        -- Define characteristic read callbacks
        if ch.uuid == light_uuid then
            local update_function = function()
                local on_off = ch.value[1]
                local red = ch.value[2]
                local green = ch.value[3]
                local blue = ch.value[4]

                bulb_label.value = string.format("Bulb is %s (color is #%X%X%X)", on_off and "ON" or "OFF", red, green, blue)
            end

            ch:add_read_callback(update_function)
            ch:subscribe(update_function)
            ch:read()
        elseif ch.uuid == morse_uuid then
            morse_ch = ch
        end

   end
end)