|  Developer
Updated on January 3, 2022

Bluetooth module description

Module provides an access to a bluetooth functionality (connect/disconnect devices, set values, get value, etc.).

Bluetooth events

The Bluetooth addon notifies a script subscribed by about state of the Bluetooth world.

Structure of an event is table.

Type of events:
Edit
Edit

discovery_started — gets sent when bluetooth devices discovery process started

fields type description
event string type of the event
Edit

discovery_stopped — gets sent when bluetooth devices discovery process stopped

fields type description
event string type of the event
Edit

device_discovered — gets sent if bluetooth device discovered

fields type description
event string type of the event
deviceAddress string bluetooth device mac address
Edit

device_removed — gets sent when bluetooth device removed

fields type description
event string type of the event
deviceAddress string bluetooth device mac address
Edit

device_connected — gets sent when bluetooth device connected

fields type description
event string type of the event
deviceAddress string bluetooth device mac address
Edit

device_disconnected — gets sent when bluetooth device disconnected

fields type description
event string type of the event
deviceAddress string bluetooth device mac address
Edit

device_paired — gets sent when bluetooth device paired

fields type description
event string type of the event
deviceAddress string bluetooth device mac address
Edit

device_unpaired — gets sent when bluetooth device unpaired

fields type description
event string type of the event
deviceAddress string bluetooth device mac address
Edit

characteristic_updated — gets sent when bluetooth device characteristic value updated

fields type description
event string type of the event
deviceAddress string bluetooth device mac address
uuid string GATT characteristic UUID
value array of bytes new characteristic value
Edit

Example: (event_handling.lua)

				
					local params = ...

if params.event == "device_connected" then
    print( "we got a device_connected event for a " .. params.deviceAddress .. " device" )
end

Bluetooth API

subscribe(script_name[, events_filter])
  • Subscribe for Bluetooth events, optionally specifying event filter rules. After subscribing the script will be launched for each event happens on a Bluetooth addon and information about this event will be passed as a parameter.
  • params:
Edit
params type description
script name string lua script name
events_filter table events filter rules
Edit
  • return: subscriber_id (string).
Edit 
				
					local bluetooth = require "bluetooth"

bluetooth.subscribe( "HUB:bluetooth/scripts/events_handling" )
set_subscription_filters(subscriber_id, filter_rules)
Edit
params type description
subscriber_id string subscriber id
filter_rules table events filter rules
Edit
  • return: none.
Edit 
				
					local bluetooth = require "bluetooth"

bluetooth.subscribe("HUB:bluetooth/scripts/events_handling")
bluetooth.set_subscription_filters("HUB:bluetooth/scripts/events_handling", { { event = "node_added" } } )
unsubscribe
  • Unsubscribe from Bluetooth events.
  • params:
Edit
params type description
subscriber_id string subscriber id
Edit
  • return: none.
Edit 
				
					local bluetooth = require "bluetooth"

bluetooth.unsubscribe( "HUB:bluetooth/scripts/events_handling" )
start_notify
  • Start notifications for GATT characteristic.
  • params:
Edit
params type description
device address string bluetooth device mac address
uuid string GATT characteristic UUID
Edit
  • return: none.
Edit 
				
					local bluetooth = require "bluetooth"

bluetooth.start_notify("04:A3:16:9E:FB:0A", "0000ffe9-0000-1000-8000-00805f9b34fb")
stop_notify
  • Stop notifications for GATT characteristic.
  • params:
Edit
params type description
device address string bluetooth device mac address
uuid string GATT characteristic UUID
Edit
  • return: none.
Edit 
				
					local bluetooth = require "bluetooth"

bluetooth.stop_notify("04:A3:16:9E:FB:0A", "0000ffe9-0000-1000-8000-00805f9b34fb")
start_discovery
  • Start bluetooth discovery process.
  • params: none.
  • return: none.
				
					local bluetooth = require "bluetooth"

bluetooth.start_discovery()
stop_discovery
  • Stop bluetooth discovery process.
  • return: none.
				
					local bluetooth = require "bluetooth"

bluetooth.stop_discovery()
remove_device
  • Remove bluetooth device
  • params:
Edit
params type description
device address string bluetooth device mac address
Edit
  • return: none.
Edit 
				
					local bluetooth = require "bluetooth"

bluetooth.removeDevice("04:A3:16:9E:FB:0A")
connect_to_device
  • Connect to bluetooth device
  • params:
Edit
params type description
device address string bluetooth device mac address
Edit
  • return: none.
Edit 
				
					local bluetooth = require "bluetooth"

bluetooth.connect_to_device("04:A3:16:9E:FB:0A")
disconnect_device
  • Disconnect from bluetooth device
  • params:
Edit
params type description
device address string bluetooth device mac address
Edit
  • return: none.
Edit 
				
					local bluetooth = require "bluetooth"

bluetooth.disconnect_device("04:A3:16:9E:FB:0A")
pair
  • Pair bluetooth device
  • params:
Edit
params type description
device address string bluetooth device mac address
Edit
  • return: none.
Edit 
				
					local bluetooth = require "bluetooth"

bluetooth.pair("04:A3:16:9E:FB:0A")
write_characteristic
  • Write new device characteristic value
  • params:
Edit
params type description
device address string bluetooth device mac address
characteristic uuid string characteristic uuid
characteristic value array of bytes new characteristic value
Edit
  • return: none.
Edit 
				
					local bluetooth = require "bluetooth"

bluetooth.write_characteristic("04:A3:16:9E:FB:0A", "0000ffe9-0000-1000-8000-00805f9b34fb", {0xFF, 0xF0, 0x0F})
read_characteristic
  • Read device characteristic value
  • params:
Edit
params type description
device address string bluetooth device mac address
characteristic uuid string characteristic uuid
Edit
  • return: none.
Edit 
				
					local bluetooth = require "bluetooth"

bluetooth.read_characteristic("04:A3:16:9E:FB:0A", "0000ffe9-0000-1000-8000-00805f9b34fb")