LELO F1S SDK BLE Specification.
This file defines the BLE interface that your F1S exposes to a controlling central. It holds information on the BLE services you'll need to search for and the characteristics you'll need to achieve desired effects.
While designing the F1S device we made sure to protect you and your device from unwanted access by anyone but yourself. One of the security features is a characteristic named Key state which will block the device from functioning unless the user physically confirms the connection, which is done by pressing the power button on the F1S device after the connection has already been established.
A logic flow diagram would contain the following steps:
- The user starts the app, which starts scanning for devices
- The user powers up the F1S device
- The app connects to the F1S device
- After connecting the app shows a message to the user, prompting them to press the power button again
- The app monitors the
Key statecharacteristic - After
Key stateis set to01(ortrue) the app continues operation.
When starting the calibration process, the device should be placed upright on a flat surface with the buttons facing upwards, after which a value of 0xFFFFFF should be written to the Motor Control characteristic (0xFFF1).
The apps UI should clarify this process to the user.
Please use the Motor control characteristic for this. Writing a 0x01FA will cause your F1S device to shut down.
Please note that your F1S device will lock all buttons while the motors are running.
Out of the BLE services your F1S device exposes the following are the ones you'll be interested in:
- Device Information Service (0x180A)
- Battery Service (0x180F)
- LELO Custom Service (0xFFF0)
In the listed services you'll find a number of characteristics, which allow reading from your devices sensors as well as control its various motors and behaviours.
The Device Information Service (0x180A) is a common BLE service in which you'll find the following characteristics (all are read-only):
| Characteristic | UUID | Type | Description | Note |
|---|---|---|---|---|
| Manufacturer name | 0x2A29 | String | Ascii encoded name of the manufacturer | LELO |
| Model number | 0x2A24 | String | Ascii encoded model name of your F1S device | F1s |
| Hardware revision | 0x2A27 | String | Ascii encoded hardware revision of your F1S | F1s REV.D |
| Firmware revision | 0x2A26 | String | Ascii encoded firmware revision installed on your F1S | F1s PRE SVN_2404 |
| Software revision | 0x2A28 | String | Ascii encoded software revision installed on your F1S | F1s Rev.B |
| MAC address | 0x0A06 | String | Ascii encoded BLE MAC address of your F1S device | double colons (:) are removed; True value is returned only after connection is confirmed |
| Serial number | 0x0A05 | String | Ascii encoded serial number of your F1S device | True value provided only after connection is confirmed |
The Battery Service (0x180F) is another common BLE service in which you'll find a single characteristic, which you can either read from or enable notify for:
| Characteristic | UUID | Type | Description | Note |
|---|---|---|---|---|
| Battery level | 0x2A19 | Byte | Single byte representing the battery level of your F1S device | Value 0-100% (0x00-0x64) |
This service holds the interesting characteristics, the ones you'll use to make the device do what you want it to do, while reading the characteristics to sense how the device is being used.
While some of these characteristics are read only, others can be written to and some support the notify functionality. This will be specified in the Access column with the letters R, W and N representing Read, Write and Notify, respectively.
With the exception of Key state none of these characteristics may be accessed until the connection to your device is confirmed (Key state is 01 or true).
| Characteristic | UUID | Access | Description | Note |
|---|---|---|---|---|
| Motor control | 0xFFF1 | R / W | Motor rotation speed | Both main and vibrator motors |
| Cruise control | 0x0AA5 | R / W | Enable the Hall sensors in your F1S devices cap | |
| Vibrator setting | 0x0A0D | R / W | Set vibration level for individual depth sensor values | |
| Key state | 0x0A0F | R / N | Security feature to protect you and your device. Used for connection confirmation | |
| Wake up | 0x0AA1 | R / W | Allows quick connection to the device without requiring the user to press the power button | The connection will still need to be confirmed |
| Hall sensor | 0x0AA3 | R / N | Main motor rotation speed | Rotations per second |
| Depth sensor | 0x0A0B | R / N | 8 touch sensors in the chamber combined into a single value | |
| Accelerometer | 0x0A0C | R / N | Accelerometer sensor in your F1S device | Separate values for the x, y, z axis |
| Pressure & Temperature | 0x0A0A | R / N | Air pressure and temperature inside your device | in mbar and ℃ respectively |
| Buttons | 0x0AA4 | R / N | The state of your F1S device buttons | +, - and power |
| Use log | 0x0A04 | R / W | Device use log / counter | Counts number of sessions (or resets the same) |
The rest of this document contains a more detailed description of our individual custom characteristics, the data they require or return, and of course, the function they perform and/or support.
| UUID | Operations | Data Length | Description |
|---|---|---|---|
| 0xFFF1 | Read, Write | 3 bytes | This characteristic is used to control your F1S devices main motor, the vibration motor, to turn off your device and to calibrate the accelerometer in your device. |
When reading from this characteristic, you'll receive 3 bytes of data, which should be interpreted as a 24 bit unsigned integer: 0x01yyzz
The first 8 bits will always be 0x01, while the second and third 8 bits (yy and zz in the above hex representation, respectively) represent the main motors speed (0-100%, 0x00-0x64) and the vibrator motors speed (0-100%, 0x00-0x64).
When writing to this characteristic, you can trigger multiple functions:
| Value | Function | Description |
|---|---|---|
| 0x01yyzz | Set motor speeds | Allows your code to set both the main motors speed as well as the speed of the vibration motor. The yy and values are defined the same as explained above in the Read section for this characteristic. Please note that below 30% the motors might not rotate, depending on the battery level of your F1S device. Also note that setting the motor speeds will lock your F1S devices physical buttons. |
| 0x01FF | Stop motors | Stops all motor activity and unlock the physical buttons. The last set motor parameters will be remembered, and if any of the caps sensors are triggered, the device will start vibrating at last set speed again. |
| 0x01FA | Shutdown the device | Stops all the devices motors and shuts the device down. |
| 0xFFFFFF | Verify Accelerometer | This is used to verify and/or calibrate the accelerometer data. The device should be placed upright (with the buttons facing upwards), after which the x and y values from the accelerometer should approach 0, and the z value will approach 1024. |
| UUID | Operations | Data Length | Description |
|---|---|---|---|
| 0x0AA4 | Read, Write | 1 byte | Enable the hall sensors in your F1S devices cap. |
Cruise control controls the devices vibration speed depending on the Hall sensors value. (see Vibrator setting and Depth)
| Value | Meaning | Note |
|---|---|---|
| 0x00 | Hall cap sensors are disabled | |
| 0x01 | Hall cap sensors are enabled | |
| 0x02 | Enable cap sensors and reset speed settings to default values | Write only |
Returns a single byte representing one of the states listed above.
Write a single byte with a value from the table above.
| UUID | Operations | Data Length | Description |
|---|---|---|---|
| 0x0A0D | Read, Write | 8 bytes | Set the vibrator motor speed setting for the corresponding cap sensor. |
As each cap sensor (8 of them in total, see Depth for additional data) is triggered, a certain vibration speed can be trigger automatically.
When reading from this characteristic, 8 bytes will be returned, with each byte representing a vibration speed setting (0-100%, 0x00-0x64), on for each cap sensor.
Write 8 bytes to this characteristic to set the vibration speed for each triggered cap sensor (see Read above for details on the values).
| UUID | Operations | Data Length | Description |
|---|---|---|---|
| 0x0A0F | Read, Notify | 1 byte | A security feature to protect your F1S device and yourself. To unlock the full functionality of your F1S device you need to confirm a connection by pressing the power button after a connection is established. This characteristic will reflect the state of the confirmation process. |
The format of the data is the same when reading or receiving notifications from this characteristic.
| Value | Meaning |
|---|---|
| 0x00 | Connection not confirmed, limited functionality. |
| 0x01 | Connection confirmed, full functionality enabled. |
| UUID | Operations | Data Length | Description |
|---|---|---|---|
| 0x0AA1 | Read, Write | 1 byte | Your F1S device can either be fully powered off or exist in a "sleep mode" state, in which it will still send out BLE advertisements (although sparsely), which means an app can connect to the device without the user pressing the power button. Note that the connection will still need to be confirmed, though. |
Reading from this characteristic will return a single byte, with it's value meaning the following:
| Value | Meaning |
|---|---|
| 0x00 | Wake up function disabled, device will fully power down. |
| 0x01 | Wake up function enabled, device will send out occasional BLE advertisements and can be connected to. |
When writing to this characteristic, write a single byte as described for Read above.
| UUID | Operations | Data Length | Description |
|---|---|---|---|
| 0x0AA3 | Read, Notify | 2 bytes | Represents the current motor speed in rotations per second. |
This characteristic can both be read from as well as set up to notify the app of changes. It's format is a 16 bit unsigned integer number which represents the main motors rotation speed in rotations per second.
| UUID | Operations | Data Length | Description |
|---|---|---|---|
| 0x0A0B | Read, Notify | 2 bytes | Represents the deepest triggered cap sensor. |
This characteristic can both be read from as well as set up to notify the app of changes. It's format is a 16 bit unsigned integer number which represents the deepest triggered cap sensor in your F1S device. There are 8 cap sensors, so this value ranges from 0x0000-0x0008.
The value this characteristic gives you represents the thrust depth of whats inserted into your F1S device.
| UUID | Operations | Data Length | Description |
|---|---|---|---|
| 0x0A0C | Read, Notify | 6 bytes | Represents the 3 axis accelerometer and/or the orientation of your F1S device. |
This characteristic can both be read from as well as set up to notify the app of changes. The data delivered will consist of 6 bytes, with individual byte pairs (16 bit) representing the readout for a single axis: 0x xxxx yyyy zzzz.
| UUID | Operations | Data Length | Description |
|---|---|---|---|
| 0x0A0A | Read, Notify | 8 bytes | Reads the pressure and temperature inside the devices chamber. |
You may either trigger a read from this characteristic or enable notifications for it. Either way, you'll receive 8 bytes of data, which should be interpreted as two 32 bit unsigned integers: 0x yyy FF zzzz, with yyyy representing the temperature, zzzz representing the pressure and both are separated by a single byte with value 0xFF.
Pressure
The pressure is a fixed floating point number, expressed in millibars (mbar), meaning the value should be converted into a floating point number and divided by 100:
0x00018AE0 => 101088 => 1010.88mbar
Temperature
Likewise, the temperature is delivered as a fixed floating point value, expressed in degrees Celsius (℃), meaning the value should be converted into a floating point number and divided by 100:
0x00000A86 => 2694 => 26.94℃
| UUID | Operations | Data Length | Description |
|---|---|---|---|
| 0x0AA4 | Read, Notify | 1 byte | Indicates what device button is pressed down. |
Reading (or watching for notifications) from this characteristic allows the app to react to button presses and release events. The following values may be delivered to the app:
| Value | Meaning |
|---|---|
| 0x00 | The central power button was pressed down. |
| 0x01 | The + button was pressed down. |
| 0x02 | The - button was pressed down. |
| 0x03 | All buttons were released. |
| UUID | Operations | Data Length | Description |
|---|---|---|---|
| 0x0A04 | Read, Write | 2 bytes | A value counting the number of times the device was used. |
Reading from this characteristic will return a 16 bit unsigned integer value representing the number of times your F1S device has been used.
This counter will increase for each session lasting 30 seconds or more. We define a session as the time between the devices startup and its shutdown. This means that if the devices is powered up, left for at least 30 seconds and then powered down, this will be recorded as a session.
If however the device is powered down less than 30 seconds after powering up, this is not counted as a session and the Use log counter will not increase.
Please note that we've simplified the explanation a bit, but in reality it's not 30s from powering up the device, but rather after the device finishes its initialisation.
Writing a value of 0xEE to this characteristic will cause your F1S device to reset this counter to 0.