Skip to content

BLE Simulator Guide

About

The BLE simulator is a configurable GATT attribute server which runs on a virtual BLE adapter. GATT Attributes can be created and their values updated through the use of a Lua script.

Running

Environment Variables

Option Expected Values Description
RUN_BLUEZ true/false This can be set to make the docker container run bluez, so that the simulator can be used even if the host machine is not running bluez.
DEVICE_COUNT Positive integer from 1-15 This environment variable is used in conjunction with RUN_BLUEZ. Simulated devices are sometimes not discoverable. This variable ensures that the devices created in the lua scripts are. The value of this should match the number of devices created in the lua script.

Docker options

Bind the system bus

-v /var/run/dbus/system_bus_socket:/var/run/dbus/system_bus_socket

Run the contianer as privileged

--privileged

Note

If you are using the RUN_BLUEZ environment variable, you will have to also:

  • Mount the host /etc/dbus-1/system.d to the contianer
    • -v /etc/dbus-1/system.d/:/etc/dbus-1/system.d
  • Bind the host's ns to the container
    • --mount type=bind,source=/proc/1/ns/,target=/rootns

Simulator Arguments

Option Arguments Description Example
--script path - Path to the lua script Lua script to interact with the gatt server and create GATT attributes --script my-script.lua
--logging level - Can be {NONE|INFO|ERROR|WARN|DEBUG|TRACE} Sets the logging level of the simulator --logging my-script.lua
--help N/A Prints a help message --help

Example command

The following example will run bluez alongside the simulator. 

docker run --rm -d --name=ble-sim \
  -e RUN_BLUEZ=true \
  -e DEVICE_COUNT=1 \
  --privileged \
  -v /var/run/dbus/system_bus_socket/:/var/run/dbus/system_bus_socket/ \
  -v /etc/dbus-1/system.d/:/etc/dbus-1/system.d \
  --mount type=bind,source=/proc/1/ns/,target=/rootns \
  iotechsys/ble-sim:1.0 \
  --script /example-scripts/device-service-example.lua

Lua Scripting

To create and use your own lua script, See Lua Scripting.

There are a number of example scripts provided within the docker container under the directory /example-scripts/ (See Lua Scripting Examples).