Bluetooth Commander
User guide
Sensor data commands
Introduction to dynamic commands with sensor data
This page is under construction. Information might change during development and testing process.
To understand basic principles of Bluetooth commander app it is highly recommended to start with some basics.
This section of user guide describes how to create a hexadecimal commands with variable value(s) - command which payload (or part of its payload) dynamically changes based on measured parameters such as:
time
acceleration in individual axis
phone temperature
phone battery level
GPS location (latitude and longitude)
proximity
Simple example of a variable command can be a frame consisting of first byte with fixed value 0xC1 (can be used on receiver side as an index byte), followed by measured value of a temperature, say 30.1°C. Utilizing offset and resolution (see table Variable scaling below) such value is converted to hexadecimal value 0x02BD and will be dynamically updated based on measured temperature.
Example of variable command with sensor data. 0x02BD is a variable part - measured temperature.
Frame of a variable command can be constructed from a multiple parameters and/or fixed values if needed. The purpose of a byte with fixed value can be for example as an index byte, to help the receiver of the message to identify it or parse its content.
Creating command with sensor data
To create a command with sensor data, click on a last item in the command list in basic layout, or on a button in custom or gamepad layouts and select "HEX - sensor data". You can enter a command name and change an icon to quickly identify it. Notice that you cannot edit text box with command value. For this type of a command it is generated automatically based on a parameter(s) added to this command. This field is also renamed and called Frame preview.
To add a parameter to the command click on a button "Click to add byte(s)". You can than select a parameter from the list. Depending on the length of the selected parameter, actual byte(s) representing its value will be added to the command. Add more parameters if you need. Frame preview should be automatically updated depending on actual sensor data. If you want to remove parameter from the list, use long click on the item and select "Remove".
There is a parameter "Fixed value" which, as name implies, has fixed value. You can add it to the command frame, typically on a first place and use it as a multiplexor signal. You can set its value within range of <0x00 - 0xFF> and us it on a receiver side to determine meaning of a data that follows. For example you can have 4 different variable commands set up as follows:
fixed value 0xA1 followed by acceleration in X axis,
fixed value 0xA2 followed by acceleration in Y axis,
fixed value 0xA3 followed by acceleration in Z axis,
fixed value 0xB1 followed by measured temperature.
Each time receiver receives a message, it can check first (index) byte and correctly process and 'understand' data that follows.
Click this button to add parameters to the command.
To access additional options for a variable command click on the three lines icon at the top. These options are the same as for HEX command with fixed value.
When you have added all the parameters and set up all the options you need to the command click "Add command". Command will be added to the list of commands (basic layout) or assigned to the button (gamepad and custom layout).
Click three lines (top-right) to access additional command options.
Variable scaling
Following table summarizes variable scaling for sensor data which are available to be broadcasted in a current app version. See following section with an example and an explanation of how to use this data.
Transmitter side: sensor data to hexadecimal value
Sensor data (sensor values) are usually floating point numbers with possible negative values. Such value is recalculated by the app into scaled value (unsigned integer) using equation:
scaled_value = (sensor_value + offset) / resolution (eq. 1)
Scaled value is then converted into hexadecimal value (displayed in app) and aligned to data length (byte count) of that particular parameter. Let`s see an example where we want to transmit command (data) containing GPS latitude. Following steps from previous section we add GPS latitude parameter to the list. App then works as follows:
App got sensor readback from Android OS for parameter GPS latitude = 48,96242°.
From table Variable scaling: GPS latitude offset is 210 and resolution is 0.0000001° / bit
Using eq. 1, scaled value is then computed as (48,96242 + 210) / 0.0000001 = 2589624200 (number computed by app will be in fact 2589624195, see explanation in next section).
Hexadecimal value of 2589624195 is 0x9A5A8783.
In current app version sensor data are inserted into command frame most significant byte first. Currently this is not configurable, however you can still select byte order for whole command frame in command options.
Receiver side: decoding received hexadecimal value
To decode received hexadecimal value on a receiver side, use following equation:
sensor_value = (scaled_value x resolution) - offset (eq. 2)
Let`s try it and continue with previous example with GPS latitude. We know that on a receiver side you receive a hexadecimal value of 0x9A5A8783 which you want to decode to actual GPS latitude value:
As previously stated, byte order in sensor data is most significant byte first, so we can directly convert received value of 0x9A5A8783 to decimal value, 0x9A5A8783 = 2589624195.
Using table Variable scaling, we see that scaling for this variable is 0.0000001°/bit, so we multiply 2589624195 x 0.0000001 = 258,9624195.
Last step is to subtract offset value of 210, so 258,9624195 - 210 = 48,9624195 which is our result.
Notice that resulting value of 48,9624195° differs on the 6th decimal place with original value of 48,96242°. This is because when app displays sensor data, each parameter has specified number of decimal places to which app rounds this number - just for display purposes. It would be 'ugly' to display numbers such as 48,962419559468249724° - such small decimal places has little practical value anyway. However for sensor_value in eq. 1 this precise number is used. And this may result in 1 digit difference (depending on a rounding method you use on a receiver side) between displayed and decoded value.
Practical usage of sensor data broadcasting
Although you can create a command with sensor data which is send when button is pressed in the app, it is more convenient to define a send period for such command to keep periodical data transfer to receiver - to keep receiver side periodically updated. When determining this send period, you should consider your application needs, capabilities of a receiver and a transmitter - your phone - especially if you need to transfer a lot of data fast. Note also that sensor data are not filtered by BT Commander app, so a digital filter on receiver side is a good idea.
No data plausibility check is performed by BT Commander app. So it is up to the receiver side to determine if a temperature of 40°C or acceleration of 30m.s^-2 is possible depending on a current application. If a sensor is defective, or sends invalid data to the app (for example wrong GPS coordinates due to the poor accuracy, or obsolete GPS coordinates of last location) app will simply send such data obtained from the sensor (in fact it is obtained from Android OS). Key point being, that it is recommended to do a data integrity check on a receiver side.
Currently, no CRC is computed over data being transmitted, but such feature might be added in the future if needed.
Specific features of some sensors
Following section describes some specific features of sensors that are available in app.
Proximity sensor
From Android docs:
Proximity sensor measures the proximity of an object in cm relative to the view screen of a device. This sensor is typically used to determine whether a handset is being held up to a person's ear.
However, most devices only return two values, one value for "near" and one for "far". These values also vary with device. Phones I used for testing typically reported values of 0 (near) and 1 (far) or 0 (near) and 8 (far).
FAQ
Q: Some sensor values are 0 (e.g. GPS longitude until GPS location is obtained), however its hexadecimal values are non zero. Is there a bug in conversion?
A: No, you need to take an parameter offset into account. Parameters with actual value zero, but with non zero offset will have non zero hexadecimal representation.
Q: Readback from acceleration sensor for one axis is always around 10m.s^-2 even if phone is laying still on a table. Why?
A: This is because the reading from acceleration sensor includes gravity. It is possible to exclude gravity (on a phone side). If such feature is needed, just let me know.
Q: Each time a command with GPS latitude or longitude is added a notification without any interesting information appears on a phone. Is this needed?
A: Yes. This notification informs user that a service is running which has access to the location data. If a service displays a notification it is considered as running in a foreground, thus preventing Android OS to kill this process (for example when app is in the background). Also using a service running in a background (without any notification) with an access to phone location data is restricted by Google (for user protection) and requires special permission and approval from Mr. Google.