Bluetooth support

From phyphox
Jump to: navigation, search

Bluetooth can be a great way to add external sensors like a thermometer or humidity sensor to your phone and in general it is a nice interface to exchange data with other projects. However, existing bluetooth devices may communicate through many different standards (bluetooth classic or modern Bluetooth 4.0 / BLE), different modes (services, a virtual serial port) and depending on the service in many different protocols (on a serial connection virtually any protocol could be used). Therefore, a universal bluetooth support is almost impossible.

Overview of Bluetooth in phyphox

Goal

As explained above, a universal support is not realistic. So, you will not be able to take any bluetooth device you own and just hook it up to phyphox. But we aim to support the following uses:

  • Connect devices that you design for phyphox. For example, if you have an Arduino-based project with a bluetooth module, we want to offer support for all common ways to communicate through this module to send and receive data.
  • Connect any BLE device by selecting services and characteristics
  • Connect external data sources, which use well-documented and not too unusual means of communication. So, if a sensor or device is meant to be used in nerdy hobby projects, we really like to add support to it. If we are able to do so obviously depends on the complexity of the device, how well it is documented and of course it really helps if we have physical access to the device. We will explicitly not reverse-engineer an undocumented device. So, if you have a device with some proprietary communication, you are out of luck unless somebody else has figured out, that it follows some generic protocol.

Current state

At the moment phyphox only supports communication through a serial bluetooth interface with few common protocols (Simple values, CSV and JSON). You can read and write through bluetooth on multiple channels by setting up your own experiment. Unfortunately, this currently is only supported on Android.

The reason that there is no support on iOS yet, is that while developing the same support as on Android we ran into the problem, that Bluetooth devices connected to the iPhone have to be certified by Apple ("Made for iPhone", Mfi) - and our test device isn't. The alternative is Bluetooth 4.0 (BLE), which does not need to be certified. We will add bluetooth support as soon as we have a use case with either a BLE or a Mfi device.

Generally, bluetooth support is not top priority, but we will add and extend it as we stumble upon devices and use cases. If you need a specific bluetooth support, please send us an email and tell us about it. If we can help, we will happily move it up on our priority list.

Documentation

As mentioned above, at the moment, bluetooth is only supported on Android and may be subject to change!

Currently, bluetooth is only supported through a serial interface. You have to pair your device with your phone (through Android's menus) and need to create your own experiment to select and read from (or write to) the device in Android. When creating this experiment you can add a bluetooth device as input or output.

Settings

You need to set "Device Address" or "Device Name". Phyphox will use the first paired device, which matches your setting. The device address has to be given in the form "00:11:22:AA:BB:CC" while the device name should be the exact name as it appears in Androids settings.

For bluetooth inputs, you may additionally define a rate and averaging. This is similar to sensor inputs: If rate is set to zero, data from the bluetooth device is added to the buffer as it is received. If rate is finite, phyphox will hold back updates from the device to match this rate (in samples per second). If you enable averaging, phyphox will average all data between updates, while without averaging it will only add the latest value and discard the others.

Protocols

A very important setting for both, input and output is the used protocol. The other settings like "output" and "separator" are specific to the protocol.

"simple" is the most simple protocol (Duh!). It just expects or sends a single string value per line. It only supports a single input or output and will split the input by a separator (a line break by default, but can be changed with the "separator" attribute).

"Comma-separated values" (CSV) is probably the most simple protocol if you want to receive separated data streams (like x, y and z component of a 3D sensor). This protocol expects a set of data per line. In each line, multiple values may be received (or sent), which are separated by a separator, which typically would be a comma or a semi colon and can be defined by the "separator" setting. The values received from a single line are then distributed to the outputs according to there position in the line. So if you receive the line "12,34,56" phyphox would write 12 to the first, 34 to the second and 56 to the third output. Writing to the bluetooth device would be done in a similar way, by filling the first, second and third input accordingly.

"JSON" writes and reads entire JSON objects at a time. In contrast to CSV you do not have to receive your values in groups, but may identify them with names and receive entire arrays for a single value at once. It will parse the JSON object and match each value within the object to the output according to the strings set in the output settings below. If arrays are received, this protocol may write multiple arrays to each output at once. Example: If the setting output 1 is set to "xvalues" and output 2 set to "yvalues" and {"xvalue": [42, 7, 1], "yvalue": [23, 24]} is received, phyphox will write 42, 7 and 1 to the first output and the second output will be filled with 23 and 24. Writing to a bluetooth device with this protocol will work similarly as JSON objects are created according to the settings "input 1", "input 2" etc.