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

precedence The precedence value for registering span init functions.
parsers Advertisement parser types for bluesee.set_adv_parser.
categories Category values for registering span init functions
widgets Widget types for use in service panels

Requirements

bluesee.register_service (uuid, callback[, options]) Registers a service panel initialization callback function against the given service UUID.

Functions

bluesee.api_version () Returns the current version of the BlueSee lua API.
bluesee.set_default_service (callback) Registers a default service panel initialization callback function.
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.
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.
bluesee.set_display_name (uuid, name) Set a display name (e.g.
bluesee.set_display_category (uuid, category) Sets the category for the given service uuid, rather than showing the ?
bluesee.new_widget (type) Returns a new widget of the given type.
bluesee.new_data (string) Returns a data object created from the passed raw binary string.

Class bluesee.Span

bluesee.Span.uuid The BLE service UUID the service panel represents.
bluesee.Span:on_service_discovered () BlueSee will call this function when the service is discovered.
bluesee.Span:on_ch_discovered (a) BlueSee will evoke this callback for each characteristic of the service, in order, when discovery is complete.
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.
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.
bluesee.Span:log (text) Logs the given text to the panel’s log tab.

Class bluesee.UUID

bluesee.UUID.new (value[, width]) A new BlueSee.UUID is constructed from the given 16-bit or 32-bit value.
bluesee.UUID.new (data) A new bluesee.UUID is constructed from the given bluesee.Data object.
bluesee.UUID:unsigned_integer () The UUID is returned as an integer.
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'

bluesee.UUID:tostring () Provides a string representation of the UUID.
bluesee.UUID:length () Provides the length of the uuid's data object.

Class bluesee.Data

bluesee.Data.endian_little The default byte order.
bluesee.Data.endian_big Represents big endianness.
bluesee.Data.new (n) Creates a new bluesee.Data object with space for n bytes (must be greater than zero).
bluesee.Data.new (value, width[, endianness]) Creates a new bluesee.Data object initialized with an integer value.
bluesee.Data.new (table) Creates a new bluesee.Data object initialized with a table of integer values.
bluesee.Data.new (string) Creates a new bluesee.Data object with a string.
bluesee.Data.new_from_binary (binary) Creates a new bluesee.Data object from a binary Lua blob (string).
bluesee.Data:as_string () Returns a Lua string representation of the data.
bluesee.Data:tostring () Returns the data object as a hexadecimal string.
bluesee.Data:length () Returns the length 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).
bluesee.Data:as_raw_string () Returns a raw representation of the data.
bluesee.Data:as_hex_string () Returns a hexadecimal representation of the data.
bluesee.Data:unsigned_integer ([endianness]) Returns an unsigned integer interpretation of the data.
bluesee.Data:signed_integer ([endianness]) Returns a signed integer interpretation of the data.
bluesee.Data:set (i, n, value[, endianness]) Sets a field of width n starting at byte i (1-indexed) to the given value.

Class bluesee.Characteristic

bluesee.Characteristic.uuid The bluesee.UUID of the characteristic, read-only
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.
ch:unsubscribe (callback) Unsubscribes for notifications from the characteristic.
ch:add_read_callback (callback) Registers a callback function that will be called whenever a read returns for the characteristic.
ch:read () Initiates a read of the characteristic.
ch:write (string) Writes the given value to the characteristic.
ch:write (data) Writes the given data to the characteristic.
ch:write (a) Writes the given table of values to the characteristic.
ch:write (value, width, byte_order) Writes the given value to the characteristic.
ch:write_binary (string) Writes the given value to the characteristic.
ch:value () Returns the last-read value for the given characteristic (doesn’t actually perform a read).
ch:unsigned_integer (endianness) Returns an unsigned integer interpretation of the characteristic value.
ch:signed_integer (endianness) Returns a signed integer interpretation of the characteristic value.

Class 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.
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).

Label Widget

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

HEX Widget

read_only (boolean) (read, write).
readable (boolean) (read, write).
bin_value (read, write).
text_value (read, write).
can_subscribe (boolean) (read, write).
is_subscribed (boolean).
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.
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.
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.

Switch Widget

enabled (boolean) (read, write).
switch.on_toggle (callback) Sets a callback to be called whenever the switch is toggled on or off.

Option Widget

enabled (boolean) (read, write).
selected_option (string) (read-only).
selected_index (integer) (read, write).
option.on_click (callback) Sets a callback to be called when the option value changes.
option:add_option (label, value) Adds a new option to the combobox.

Button Widget

enabled (boolean).
option.on_click (callback) Sets a callback to be called when the button is clicked.

Textfield Widget

value (string) (read, write).
textfield.on_value_update (callback) Registers a callback that can receive value updates, providing “on change” style event handling of user input.

Demo Script

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


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

This class represents a service panel (‘span’), encapsulating all interactions with a given BLE service and its characteristics. It is provided through the callbacks passed to the bluesee.register_service or bluesee.set_default_service functions, giving users a chance to customize the panel with widgets, define interactions, etc.
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:

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:

bluesee.Span:log (text)
Logs the given text to the panel’s log tab.

Parameters:

Class bluesee.UUID

This class represents UUIDs in the system. It is used as needed in place of strings to reduce errors in string comparison of UUIDs due to case sensitivity or presence/absence of dashes. All BlueSee functions that take a UUID can either take a string or an instance of BlueSee.UUID. All callback functions provided to BlueSee that take a UUID as a parameter will be called with an instance of BlueSee.UUID.

UUID objects support the standard Lua tostring() operator, which will return the form:

'XXXXXXXX-XXXX-XXXX-XXXX-XXXX' (hexadecimal values with lowercase alphabetic characters), ‘XXXXXXXX’, or ‘XXXX’.

UUIDs can be compared (==) to:

Integer representations of 16-bit and 32-bit UUIDs

bluesee.Data objects of length 2, 4, or 16 bytes.

Strings, in any of the forms accepted by the bluesee.UUID.new(string) constructor.

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

This class is used to represent blobs of data in the system—for example, manufacturer data from advertisements. It provides convenience functions such as subfield extraction from data structures and endianness conversion.

Data objects support the standard Lua # (length) and tostring() operators. When calling tostring(), it returns a hexadecimal representation of the string, as an alias to data:ashexstring().

To retrieve a raw version of the string, call data:as_raw_string() on the data object.

Data objects also support byte-wise access and assignment via indexing (e.g. data[3] = 255).

To assign values of greater width, use the bluesee.Data:set() method. For operations parameterized by byte order, the class contains the values bluesee.Data.endian_little and bluesee.Data.endian_big.

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

This class represents an instance of BLE characteristic. Users should not need to create instances of this class from scratch; generally they will be provided by the span’s on_ch_discover callback, or using the span’s ch_get() method.
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:

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

Widgets provide substance to spans in the form of controls, labels, and inputs.
Widgets are created by using the bluesee.new_widget(type) global function. Widgets are then added to the span.

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

The label widget displays a value associated with a title, designed to function as a key-value pairing.
value
The value of the property identified by the title property, as a string. read, write.

HEX Widget

The hex widget is used to display raw data either as a hexadecimal value, or interpreted as an ASCII string. It also provides buttons to read or write a value. This is used predominantly by the generic service script, to represent characteristics on an otherwise-unknown service.
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

The switch widget provides a simple on/off toggle. The widget’s title property is used as the label.
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

The option widget provides a combobox allowing the user to pick from one of many different values. The widget’s title property is used for the option label.
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

The button widget provides a clickable button and a Lua callback. The widget’s title property is used for the button’s text.
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

The TextField widget is designed to provide a text box for the purpose of getting user input from the value.
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)
generated by LDoc 1.4.6 Last updated 2018-01-16 16:59:52