Bluetooth Low Energy - Revision history

Sebastian Kuhlen: /* BLE as output */

2024-09-06T21:17:30Z

BLE as output

Sebastian Kuhlen: /* Phyphox event characteristic (0004) */

2024-09-06T20:32:56Z

Phyphox event characteristic (0004)

Sebastian Kuhlen: /* Phyphox event characteristic (0004) */

2022-07-20T13:48:08Z

Phyphox event characteristic (0004)

Sebastian Kuhlen at 13:47, 20 July 2022

2022-07-20T13:47:41Z

Sebastian Kuhlen: /* output conversion functions */

2022-07-17T22:27:03Z

output conversion functions

Sebastian Kuhlen: /* input conversion functions */

2021-06-16T11:27:56Z

input conversion functions

Sebastian Kuhlen: /* BLE as input */

2020-11-04T16:05:58Z

BLE as input

Sebastian Kuhlen at 20:18, 25 August 2020

2020-08-25T20:18:00Z

Sebastian Kuhlen: /* Sending phyphox-files from a device */

2020-08-17T12:46:55Z

Sending phyphox-files from a device

Sebastian Kuhlen: /* Sending phyphox-files from a device */

2020-08-17T12:46:26Z

Sending phyphox-files from a device

← Older revision		Revision as of 21:17, 6 September 2024
Line 131:		Line 131:

	In contrast to using the tag "bluetooth" within an input tag, you cannot specify a mode or a poll rate. The values are read from buffers defined in input tags and written to the device when the analysis process of the experiment has finished. Config tags work as usual.		In contrast to using the tag "bluetooth" within an input tag, you cannot specify a mode or a poll rate. The values are read from buffers defined in input tags and written to the device when the analysis process of the experiment has finished. Config tags work as usual.
		+
		+	Since phyphox file format 1.19 (phyphox version 1.2.0) you can also set the attribute "keep" for each input tag. This works like the keep attribute in analysis modules: If you set keep="false", the data container is cleared after the data has been sent, allowing you to sent data only once. The default is keep="true" and the same behavior as in older versions, in which the data container is not altered after data has been sent.

	===config, input and output block===		===config, input and output block===

@@ Line 362: / Line 362: @@
 The data block of each event consists of 17 bytes with following meaning:
-Byte 0 is the event type: PAUSE (0x00), START (0x01), SYNC (0xff). So, for example, you can look for 0xff on byte 1 to find sync events or check for 0x01 to see if phyphox is currently measuring.
+Byte 0 is the event type: PAUSE (0x00), START (0x01), CLEAR (0x02), SYNC (0xff). So, for example, you can look for 0xff on byte 1 to find sync events or check for 0x01 to see if phyphox is currently measuring.
 Byte 1-8 is the experiment time in milliseconds, i.e. the time the measurement has been running since the first start event. This value will not increase while the experiment is paused and for the first START event it will be zero. SYNC events will set this to -1 (i.e. 0xffffffffffffffff) as this occurs before the reference START event. The format is a 64bit signed integer in big endian format. This also means that for most applications, you can simply interpret bytes 5 to 8 as a 32bit unsigned integer (big endian) to get millis since the start of the measurement without running into any problems as long as the measurement does not run longer than about three weeks. (In fact, the choice for 64bit signed was just made for consistency with Java system time and there is not much practical relevance to interpreting it as 64bit over 32bit.)
@@ Line 371: / Line 371: @@
 This feature is available since phyphox file format 1.15 (version 1.1.11).

← Older revision		Revision as of 13:48, 20 July 2022
Line 369:		Line 369:

	Events are sent as soon as possible with the SYNC event being as close to the actual time measurement as possible, so the SYNC event is usually the best option to get the real world clock from phyphox. Still, you should be aware that network latency can be significant, especially if multiple Bluetooth devices, bad reception or a lot of traffic is involved.		Events are sent as soon as possible with the SYNC event being as close to the actual time measurement as possible, so the SYNC event is usually the best option to get the real world clock from phyphox. Still, you should be aware that network latency can be significant, especially if multiple Bluetooth devices, bad reception or a lot of traffic is involved.
		+
		+	This feature is available since phyphox file format 1.15 (version 1.1.11).

@@ Line 330: / Line 330: @@
 :The data from the characteristic is interpreted as a 64bit floating point number with big endian byte order (that is starting with the MSB)
-==Sending phyphox-files from a device==
+==Phyphox service==
 If you create your own device (for example an Arduino-based sensor with a BLE module), you can also store experiments on the device and send them to phyphox.
@@ Line 345: / Line 355: @@
 The experiment is transmitted sequentially in subsequent messages. If there is space left in the final message, it can simply be filled with zeros as phyphox ignores any bytes after the size set in the header has been reached.

@@ Line 214: / Line 214: @@
 ===output conversion functions===
-The input tags in an output block take a number from a phyphox buffer and convert it to a binary value to be written to a characteristic. Some functions can also take the whole content of the buffer instead of a single value. Currently, the following conversion functions are defined:
+The input tags in an output block take a number from a phyphox buffer and convert it to a binary value to be written to a characteristic. Some functions can also take the whole content of the buffer instead of a single value.
 ;string

← Older revision		Revision as of 11:27, 16 June 2021
Line 262:		Line 262:

	The output tags in an input block take a byte sequence from the characteristic and convert it to a number to be written to a phyphox buffer. Most conversion functions (unless noted otherwise) can use the attributes "offset" and "size" to define a subsequence of bytes. The start is defined by "offset" (in bytes, starting at zero) and the length is set by "size" (in bytes).		The output tags in an input block take a byte sequence from the characteristic and convert it to a number to be written to a phyphox buffer. Most conversion functions (unless noted otherwise) can use the attributes "offset" and "size" to define a subsequence of bytes. The start is defined by "offset" (in bytes, starting at zero) and the length is set by "size" (in bytes).
		+
		+	Optionally, the attribute "repeating" can be set to a value larger than zero. If set, multiple values can be extracted from a single dataset and the conversion function will try and get values from [offset], [offset]+[repeating], [offset]+2*[repeating] etc.

	Instead of defining a conversion function, you can also set the attribute "extra" to "time" (extra="time"). This means that the associated buffer does not receive the value from the characteristic, but the time at which the characteristic has been read in seconds since the beginning of the experiment.		Instead of defining a conversion function, you can also set the attribute "extra" to "time" (extra="time"). This means that the associated buffer does not receive the value from the characteristic, but the time at which the characteristic has been read in seconds since the beginning of the experiment.

@@ Line 106: / Line 106: @@
 ::New values are received when the device notifies that there is a new value. The characteristic needs to support notifications. For most devices, this mode should give the best results.
 :;indication
-::New values are received when the device indicates that there is a new value. The characteristic needs to support indication, which is very uncommon for simple values. In most cases you probably want to use notifications instead.
+::New values are received when the device indicates that there is a new value. The characteristic needs to support indication, which is very uncommon for simple values. This setting is no longer relevant starting with phyphox 1.1.7 as it then auto-detects notification or indication regardless of which has been chosen here.
 ;rate
 :This attribute is only used when the mode is set to "poll" and gives the rate in Hz at which new values are polled.

@@ Line 2: / Line 2: @@
 ----
-'''Warning: The information on this page refers to version 1.1.0 (file format 1.7) onwards. Bluetooth Low Energy was not available on earlier versions of phyphox.'''
+'''If you want to integrate your Arduino or ESP32 project with phyphox, the easiest approach ist our [[Arduino library]].'''
-----
+The information on this page refers to version 1.1.0 (file format 1.7) onwards. Bluetooth Low Energy was not available on earlier versions of phyphox.
 Phyphox can communicate with almost any Bluetooth Low Energy (BLE) device to receive and send data. It comes with several prepared experiment configurations, which you can use without any additional knowledge. On top you can add support for additional devices through our editor or by directly creating/editing a phyphox-file with a text editor. If you are just looking for devices with existing support, you can check out our [[Bluetooth device database]] instead.

@@ Line 329: / Line 329: @@
 To do so, your device needs to advertise and implement the phyphox service, which uses the UUID cddf0001-30f7-4671-8b43-5e40ba53514a. When the user picks the Bluetooth scan from the "+" button on the main screen, phyphox will list devices that advertise this UUID in white like any other device for which it has an internal phyphox-file.
-When connecting to this device, phyphox will look for a characteristic with the UUID cddf0002-30f7-4671-8b43-5e40ba53514a and subscribe to its notifications. Your device needs to react to this subscription by starting to send the experiment file (preferably in a zip file) through this characteristic. Alternatively, if you cannot react to a subscription (some libraries are limited in this way), you can also offer an additional characteristic with the UUID cddf0003-30f7-4671-8b43-5e40ba53514a. If present, phyphox will write a 1 to it to request the start of the transfer and a 0 before disconnecting (if possible - you should be prepared for a disconnect that does not allow writing a zero).
+When connecting to this device, phyphox will look for a characteristic with the UUID cddf0002-30f7-4671-8b43-5e40ba53514a and subscribe to its notifications. Your device needs to react to this subscription by starting to send the experiment file (preferably in a zip file) through this characteristic. Alternatively (since phyphox version 1.1.6), if you cannot react to a subscription (some libraries are limited in this way), you can also offer an additional characteristic with the UUID cddf0003-30f7-4671-8b43-5e40ba53514a. If present, phyphox will write a 1 to it to request the start of the transfer and a 0 before disconnecting (if possible - you should be prepared for a disconnect that does not allow writing a zero).
 Sending the experiment file starts with a header. So the first package you send needs to consist of (at least 15 bytes):