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
- 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
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
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:
- 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
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
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:
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)