Add support for Freestyle Libre 3

[isotherm]

The Libre 3 reports results in a different way:

• The history reports are missing a column of unknown meaning.
• The reading reports are missing custom comments and error values.

The workaround in this pull request manipulates the Libre 3 results to look like the results for earlier models and is for demonstration and documentation purposes only. A better implementation would abstract the difference in reporting format into the drivers for each device.

This pull request is meant to start discussion on the changes, the best way to accomplish them, and also eventually to produce documentation for glucometer-protocols

[isotherm]

Here are two sample lines from $history?:

243,12,1,11,25,10,23,43,1,0,0,0,85,60,0
233,12,1,11,25,10,18,44,1,0,0,0,0,55,32768

Here are two sample lines from $arresult?:

7429,2,1,13,25,20,22,12,1,2,0,0,88,1,3,1,1,1,1,1,0,3,4,0,1,3,0,3538,7,1,13,25,20,22,12,1,2
7415,2,1,13,25,20,15,47,1,2,0,0,93,1,3,0,0,0,0,0,0,3,0,0,0,0,0,3532

The first entry was marked with all checkboxes, and with entries of 1 unit rapid-acting insulin, 2 units long-acting insulin, 3g carbs (also 1hr and 2hr reminders), exercise, medication.

[sockpuppet42]

Can confirm that with this patch applied and --driver fslibre3 I can get useful looking values out of my fslibre3 (instead of a python-stacktrace with Key error: rapid-acting-flag).

[isotherm]

Would you mind telling me what device do you use to be able to read the sensor with the pc? thanks

There is a "FreeStyle Libre 3 Reader" device which reads the sensor. This change allows a PC (or really any device) to communicate with the reader over USB and download the readings. So the PC isn't reading the sensor.

[ryan-carpenter]

I checked out this PR and successfully extracted data from a Freestyle Libre 3 Reader. The device was /dev/hidraw10 on my system.

> glucometer --driver fslibre3 --device /dev/hidraw10 patient
Patient Name: [N/A]

This is not redacted. The literal output was "[N/A]".

CSV data from dump looked like this.

> glucometer --driver fslibre3 --device /dev/hidraw10 dump
"2025-12-05 10:31:14","100.00","","CGM","(Sensor)"
"2025-12-05 19:22:32","150.00","","CGM","(Scan); Long-acting insulin (9.0); Rapid-acting insulin (2.5)"

The datetime and info commands threw an exception.

Details from datetime

> glucometer --driver fslibre3 --device /dev/hidraw10 datetime
Traceback (most recent call last):
  File "/path/to/venvs/glucometerutils/bin/glucometer", line 7, in <module>
    sys.exit(main())
             ^^^^^^
  File "/path/to/glucometerutils/glucometer.py", line 167, in main
    print(device.get_datetime())
          ^^^^^^^^^^^^^^^^^^^^^
  File "/path/to/glucometerutils/support/freestyle.py", line 114, in get_datetime
    date = self._session.send_text_command(b"$date?").rstrip("\r\n")
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/path/to/venvs/glucometerutils/lib/python3.11/site-packages/freestyle_hid/_session.py", line 379, in send_text_command
    return self._send_text_command_raw(command).decode(self._encoding, "replace")
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/path/to/venvs/glucometerutils/lib/python3.11/site-packages/freestyle_hid/_session.py", line 374, in _send_text_command_raw
    raise CommandError(repr(message) or "Command failed")
freestyle_hid._exceptions.CommandError: b''

Details from info

> glucometer --driver fslibre3 --device /dev/hidraw10 info
Traceback (most recent call last):
  File "/path/to/venvs/glucometerutils/bin/glucometer", line 7, in <module>
    sys.exit(main())
             ^^^^^^
  File "/path/to/glucometerutils/glucometer.py", line 126, in main
    time_str = device.get_datetime()
               ^^^^^^^^^^^^^^^^^^^^^
  File "/path/to/glucometerutils/support/freestyle.py", line 114, in get_datetime
    date = self._session.send_text_command(b"$date?").rstrip("\r\n")
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/path/to/venvs/glucometerutils/lib/python3.11/site-packages/freestyle_hid/_session.py", line 379, in send_text_command
    return self._send_text_command_raw(command).decode(self._encoding, "replace")
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/path/to/venvs/glucometerutils/lib/python3.11/site-packages/freestyle_hid/_session.py", line 374, in _send_text_command_raw
    raise CommandError(repr(message) or "Command failed")
freestyle_hid._exceptions.CommandError: b''

As far as I can tell, all the dependencies are satisfied. However, I think the installed python version is higher than specified, which might be a problem. Reader malfunction is another possibility, since the screen and maybe other components were damaged by water. The Abbot uploader for Windows failed to get any data from this damaged Freestyle Reader, but the csv dump from glucometerutils appears to be complete with respect to glucose data and manual entries.

[isotherm]

The datetime and info commands threw an exception.

As far as I can tell, all the dependencies are satisfied. However, I think the installed python version is higher than specified, which might be a problem. Reader malfunction is another possibility, since the screen and maybe other components were damaged by water. The Abbot uploader for Windows failed to get any data from this damaged Freestyle Reader, but the csv dump from glucometerutils appears to be complete with respect to glucose data and manual entries.

I am testing locally with Python 3.11.2, and datetime and info commands are working fine. Reader malfunction is a definite possibility, give the circumstances you describe, especially given the fact that the official Windows software couldn't get any data at all.

You can try using --set command (or interactive console commands) to set the date and patient name. It's possible that might restore the reader's ability to be read normally.

[ryan-carpenter]

You can try using --set command (or interactive console commands) to set the date and patient name. It's possible that might restore the reader's ability to be read normally.

Wow. It worked. Thanks!
After I set the date and time, the glucometer info command worked and so did the LibreView uploader in Windows.

> glucometer --driver fslibre3 --device /dev/hidraw28 datetime --set
2026-01-15 15:49:00

> glucometer --driver fslibre3 --device /dev/hidraw28 info
FreeStyle Libre 3
Serial Number: ABCD123-E4567
Version Information:
    Software version: 1.0.14
Native Unit: mg/dL
Time: 2026-01-15 15:49:00

I compared the the glucometer dump to a download from LibreView. The first three field names were Device, Serial Number, Device Timestamp, and Record Type. The table below shows how the fields map from LibreView to the glucometer dump. For example, rows that contained values in the Historic Glucose mg/dL were classified as Record Type "0" in LibreView and "CGM","(Sensor)" in the glucometer dump. This is based on the glucometer dump only. I did not try using the interactive console.

LibreView field name	LibreView record type	How the record type appears in glucometer dump	Note
Historic Glucose mg/dL	0	"CGM","(Sensor)"
Scan Glucose mg/dL	1	"CGM","(Scan)"	Glucose values at the time of viewing.
Non-numeric Rapid-Acting Insulin	4	"CGM","(Scan)"	Empty or "1" (Rapid-acting insulin recorded without a quantity)
Rapid-Acting Insulin (units)	4	"CGM","(Scan)"
Non-numeric Food	5	"CGM","(Scan)"	Empty or "1" (Food recorded without a quantity)
Carbohydrates (grams)	5	"CGM","(Scan)"
Carbohydrates (servings)	5	"CGM","(Scan)"
Non-numeric Long-Acting Insulin	4	"CGM","(Scan)"	Empty or "1" (Long-acting insulin recorded without a quantity)
Long-Acting Insulin (units)	4	"CGM","(Scan)"
Notes	?	?	None recorded on this Reader
Strip Glucose mg/dL	?	?	None recorded on this Reader
Ketone mmol/L	?	?	None recorded on this Reader
Meal Insulin (units)	?	?	None recorded on this Reader
Correction Insulin (units)	?	?	None recorded on this Reader
User Change Insulin (units)	?	?	None recorded on this Reader
Unknown	6	"CGM","(Scan)"	Timestamps correspond to high or low glucose events. All main data fields are empty and the corresponding glucose values are recorded separately in other rows of Record Type "0".