bckelley/tconnectsync
1
0
Fork 0
mirror of https://github.com/bckelley/tconnectsync.git synced 2026-08-24 03:34:12 -05:00
Code Issues Packages Projects Releases Wiki Activity

README: update with pip installation mechanism, and clarify installation steps

Browse Source
This commit is contained in:
James Woglom
2021-10-20 01:28:43 -04:00
parent bcd486561f
commit b53fb9c099
1 changed files with 176 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+176 -37
View File
@@ -9,19 +9,32 @@ If you have a t:slim X2 pump with the companion t:connect mobile Android or iOS
At a high level, tconnectsync works by querying Tandem's undocumented APIs to receive basal and bolus data from t:connect, and then uploads that data as treatment objects to Nightscout. It contains features for checking for new Tandem pump data continuously, and updating that data along with the pump's reported IOB value to Nightscout whenever there is new data.
**To get started,** read the setup instructions below and choose whether to run the application via **Pipenv** or **Docker**.
When you run the program with no arguments, it performs a single cycle of the following, and exits after completion:
## Tandem APIs
* Queries for basal information via the t:connect ControlIQ API.
* Queries for bolus, basal, and IOB data via the t:connect non-ControlIQ API.
* Merges the basal information received from the two APIs. (If using ControlIQ, then basal information appears only on the ControlIQ API. If not using ControlIQ, it appears only on the legacy API.)
* Queries Nightscout for the most recently created Temp Basal object by tconnectsync, and uploads all data newer than that.
* Queries Nightscout for the most recently created Bolus object by tconnectsync, and uploads all data newer than that.
* Uploads a single Nightscout Activity object representing the current IOB as reported by the pump.
This application utilizes three separate Tandem APIs for obtaining t:connect data, referenced here by the identifying part of their URLs:
If run with the `--auto-update` flag, then the application performs the following steps:
* [**controliq**](https://github.com/jwoglom/tconnectsync/blob/master/tconnectsync/api/controliq.py) - Contains Control:IQ related data, namely a timeline of all Basal events uploaded by the pump, separated by type (temp basals, algorithmically-updated basals, or profile-updated basals).
* [**android**](https://github.com/jwoglom/tconnectsync/blob/master/tconnectsync/api/android.py) - Used internally by the t:connect Android app, these API endpoints were discovered by reverse-engineering the Android app. Most of the API endpoints are used for uploading pump data, and tconnectsync uses one endpoint which returns the most recent event ID uploaded by the pump, so we know when more data has been uploaded.
* [**tconnectws2**](https://github.com/jwoglom/tconnectsync/blob/master/tconnectsync/api/ws2.py) - More legacy than the others, this seems to power the bulk of the main t:connect website. It is used to retrieve a CSV export of non-ControlIQ basal data, as well as bolus and IOB data. (I haven't found any mentions of bolus or IOB data in the Control:IQ-specific API.)
* Queries an API endpoint used only by the t:connect mobile app which returns an internal event ID, corresponding to the most recent event published by the mobile app.
* Whenever the internal event ID changes (denoting that the mobile app uploaded new data to synchronize), perform all of the above mentioned steps to synchronize data.
## Setup
Create a file named `.env` containing configuration values inside the checked-out tconnectsync folder (the same folder as `main.py`). You should specify the following parameters:
**To get started,** you need to choose whether to install the application via
**Pip**, **Pipenv**, or **Docker**.
After that, you can choose to run the program continuously via **Supervisord**
or on a regular interval with **Cron**.
## Installation
First, create a file named `.env` containing configuration values.
You should specify the following parameters:
```bash
# Your credentials for t:connect
@@ -43,53 +56,91 @@ These values can alternatively be specified via environment variables.
The .env file contains your t:connect username and password, Tandem pump serial number (which is utilized in API calls to t:connect), your Nightscout URL and secret token (for uploading data to Nightscout), and local timezone (the timezone used in t:connect).
I have only tested tconnectsync with a Tandem pump set in the US Eastern timezone. Tandem's (to us, undocumented) APIs are [a bit loose with timezones](https://github.com/jwoglom/tconnectsync/blob/master/tconnectsync/parser.py#L15), so please let me know if you notice any timezone-related bugs.
### Installation via Pip
When you run the program with no arguments, it performs a single cycle of the following, and exits after completion:
This is the easiest method to install.
* Queries for basal information via the t:connect ControlIQ API.
* Queries for bolus, basal, and IOB data via the t:connect non-ControlIQ API.
* Merges the basal information received from the two APIs. (If using ControlIQ, then basal information appears only on the ControlIQ API. If not using ControlIQ, it appears only on the legacy API.)
* Queries Nightscout for the most recently created Temp Basal object by tconnectsync, and uploads all data newer than that.
* Queries Nightscout for the most recently created Bolus object by tconnectsync, and uploads all data newer than that.
* Uploads a single Nightscout Activity object representing the current IOB as reported by the pump.
First, ensure that you have **Python 3** with **Pip** installed on your
Linux machine. Then, install tconnectsync from pip:
If run with the `--auto-update` flag, then the application performs the following steps:
```
$ pip3 install tconnectsync
```
* Queries an API endpoint used only by the t:connect mobile app which returns an internal event ID, corresponding to the most recent event published by the mobile app.
* Whenever the internal event ID changes (denoting that the mobile app uploaded new data to synchronize), perform all of the above mentioned steps to synchronize data.
After this, you should be able to view tconnectsync's help with:
```
$ tconnectsync --help
usage: tconnectsync [-h] [--version] [--pretend] [-v] [--start-date START_DATE] [--end-date END_DATE] [--days DAYS] [--auto-update] [--check-login]
### Running with Pipenv
Syncs bolus, basal, and IOB data from Tandem Diabetes t:connect to Nightscout.
You can run the application using Pipenv. Assuming you have only Python 3 and pip installed, install pipenv with `pip3 install pipenv`. Then install tconnectsync's dependencies with `pipenv install`, and you can launch the program with `pipenv run tconnectsync` (which, through an alias defined in `Pipfile`, runs ``pipenv run python3 main.py`).
optional arguments:
-h, --help show this help message and exit
--version show program's version number and exit
--pretend Pretend mode: do not upload any data to Nightscout.
-v, --verbose Verbose mode: show extra logging details
--start-date START_DATE
The oldest date to process data from. Must be specified with --end-date.
--end-date END_DATE The newest date to process data until (inclusive). Must be specified with --start-date.
--days DAYS The number of days of t:connect data to read in. Cannot be used with --from-date and --until-date.
--auto-update If set, continuously checks for updates from t:connect and syncs with Nightscout.
--check-login If set, checks that the provided t:connect credentials can be used to log in.
```
Go to the folder where you created the `.env` file, and run:
```
$ tconnectsync --check-login
```
If you receive no errors, then you can move on to the **Running Tconnectsync Continuously** section.
### Installing with Pipenv
You can run the application using Pipenv.
First, ensure you have Python 3 and pip installed, then install pipenv with `pip3 install pipenv`.
Clone the Git repository for tconnectsync and cd into it with:
```
$ git clone https://github.com/jwoglom/tconnectsync
$ cd tconnectsync
```
Then install tconnectsync's dependencies with `pipenv install`.
Afterwards, you can launch the program with `pipenv run tconnectsync` so long as
you are inside the checked-out tconnectsync folder.
```bash
$ git clone https://github.com/jwoglom/tconnectsync && cd tconnectsync
$ pip3 install pipenv
$ pipenv install
$ pipenv run tconnectsync --help
usage: main.py [-h] [--pretend] [--start-date START_DATE] [--end-date END_DATE]
[--days DAYS] [--auto-update]
usage: main.py [-h] [--version] [--pretend] [-v] [--start-date START_DATE] [--end-date END_DATE] [--days DAYS] [--auto-update] [--check-login]
Syncs bolus, basal, and IOB data from Tandem Diabetes t:connect to Nightscout.
optional arguments:
-h, --help show this help message and exit
--version show program's version number and exit
--pretend Pretend mode: do not upload any data to Nightscout.
-v, --verbose Verbose mode: show extra logging details
--start-date START_DATE
The oldest date to process data from. Must be specified with
--end-date.
--end-date END_DATE The newest date to process data until (inclusive). Must be
specified with --start-date.
--days DAYS The number of days of t:connect data to read in. Cannot be
used with --from-date and --until-date.
--auto-update If set, continuously checks for updates from t:connect and
syncs with Nightscout.
The oldest date to process data from. Must be specified with --end-date.
--end-date END_DATE The newest date to process data until (inclusive). Must be specified with --start-date.
--days DAYS The number of days of t:connect data to read in. Cannot be used with --from-date and --until-date.
--auto-update If set, continuously checks for updates from t:connect and syncs with Nightscout.
--check-login If set, checks that the provided t:connect credentials can be used to log in.
```
You can now continue to either the **Running with Cron** or **Running with Supervisord** sections.
### Running with Docker
Move the `.env` file you created earlier into this folder, and run:
```
$ pipenv run tconnectsync --check-login
```
If you receive no errors, then you can move on to the **Running Tconnectsync Continuously** section.
### Installing with Docker
First, [ensure that you have Docker running and installed](https://docs.docker.com/get-started/#download-and-install-docker).
@@ -104,14 +155,34 @@ To instead build the image locally and launch the project:
```bash
$ git clone https://github.com/jwoglom/tconnectsync
$ cd tconnectsync
$ docker build -t tconnectsync .
$ docker run tconnectsync --help
```
You can now continue to either the **Running with Cron** or **Running with Supervisord** sections.
Move the `.env` file you created earlier into this folder, and run:
```
$ docker run tconnectsync --check-login
```
If you receive no errors, then you can move on to the **Running Tconnectsync Continuously** section.
## Running Tconnectsync Continuously
You most likely want tconnectsync to run either continuously (via the auto-update
feature) or on a regular interval (via cron).
The supervisord approach is recommended for simplicity.
### Running with Supervisord (recommended)
To instead configure tconnectsync to run continuously in the background using its `--auto-update` feature, you can use a tool such as Supervisord. Here is an example `tconnectsync.conf` which you can place inside `/etc/supervisor/conf.d`:
To configure tconnectsync to run continuously in the background using its `--auto-update` feature, you can use a tool such as Supervisord.
First, install supervisord via your Linux system's package manager.
(For example, for Ubuntu/Debian-based systems, run `sudo apt install supervisor`)
Supervisord is configured by creating a configuration file in `/etc/supervisor/conf.d`.
Here is an example `tconnectsync.conf` which you can place in that folder:
```
[program:tconnectsync]
@@ -119,12 +190,63 @@ command=/path/to/tconnectsync/run.sh
directory=/path/to/tconnectsync/
stderr_logfile=/path/to/tconnectsync/stderr.log
stdout_logfile=/path/to/tconnectsync/stdout.log
user=tconnectsync
user=<your username>
numprocs=1
autostart=true
autorestart=true
```
In order to create a `run.sh` file, see the section below which aligns with your
choice of installation method.
After the configuration file has been created, ensure that Supervisor is running
and configured to start on boot:
```bash
$ sudo systemctl daemon-reload
$ sudo systemctl start supervisord
$ sudo systemctl enable supervisord
```
Then use the `supervisorctl` command to manage the status of the tconnectsync program:
```bash
$ sudo supervisorctl status
tconnectsync STOPPED
$ sudo supervisorctl start tconnectsync
$ sudo supervisorctl status
tconnectsync RUNNING pid 18810, uptime 00:00:05
```
You can look at the `stderr.log` and `stdout.log` files to check that tconnectsync
is running and has started up properly:
```bash
$ tail -f /path/to/tconnectsync/stdout.log
Starting auto-update between 2021-09-30 00:06:39.942273 and 2021-10-01 00:06:39.942273
2021-10-01 00:06:39 DEBUG Instantiating new AndroidApi
2021-10-01 00:06:39 DEBUG Starting new HTTPS connection (1): tdcservices.tandemdiabetes.com:443
2021-10-01 00:06:40 DEBUG https://tdcservices.tandemdiabetes.com:443 "POST /cloud/oauth2/token HTTP/1.1" 200 404
2021-10-01 00:06:40 INFO Logged in to AndroidApi successfully (expiration: 2021-10-01T08:06:40.362Z, in 7 hours, 59 minutes)
```
#### With Pip Installation
In the `tconnectsync.conf`, you should set `/path/to/tconnectsync` to the folder
containing your `.env` file.
Create a `run.sh` file containing:
```bash
#!/bin/bash
tconnectsync --auto-update
```
#### With Pipenv Installation
In the `tconnectsync.conf`, you should set `/path/to/tconnectsync` to the folder
where you checked-out the GitHub repository.
An example `run.sh` which launches tconnectsync within its pipenv-configured virtual environment:
```bash
@@ -139,7 +261,12 @@ cd /path/to/tconnectsync
exec python3 -u main.py --auto-update
```
An example `run.sh` which uses Docker:
#### With Docker Installation
In the `tconnectsync.conf`, you should set `/path/to/tconnectsync` to the folder
where you checked-out the GitHub repository.
An example `run.sh` if you installed tconnectsync via Docker:
```bash
#!/bin/bash
@@ -149,7 +276,10 @@ docker run tconnectsync --auto-update
```
### Running with Cron
To configure tconnectsync to run at a periodic interval (i.e. every 15 minutes), you can just invoke main.py with no arguments via cron.
If you choose not to run tconnectsync with `--auto-update` continuously,
you can instead run it at a periodic interval (i.e. every 15 minutes) by just
invoking tconnectsync with no arguments via cron.
If using Pipenv or a virtualenv, make sure that you either prefix the call to main.py with `pipenv run` or source the `bin/activate` file within the virtualenv, so that the proper dependencies are loaded. If not using any kind of virtualenv, you can instead just install the necessary dependencies as specified inside Pipfile globally.
@@ -162,6 +292,15 @@ An example configuration in `/etc/crontab` which runs every 15 minutes:
You can use one of the same `run.sh` files mentioned above in the Supervisord example, but remove the `--auto-update` flag since you are handling the functionality for running the script periodically yourself.
## Tandem APIs
This application utilizes three separate Tandem APIs for obtaining t:connect data, referenced here by the identifying part of their URLs:
* [**controliq**](https://github.com/jwoglom/tconnectsync/blob/master/tconnectsync/api/controliq.py) - Contains Control:IQ related data, namely a timeline of all Basal events uploaded by the pump, separated by type (temp basals, algorithmically-updated basals, or profile-updated basals).
* [**android**](https://github.com/jwoglom/tconnectsync/blob/master/tconnectsync/api/android.py) - Used internally by the t:connect Android app, these API endpoints were discovered by reverse-engineering the Android app. Most of the API endpoints are used for uploading pump data, and tconnectsync uses one endpoint which returns the most recent event ID uploaded by the pump, so we know when more data has been uploaded.
* [**tconnectws2**](https://github.com/jwoglom/tconnectsync/blob/master/tconnectsync/api/ws2.py) - More legacy than the others, this seems to power the bulk of the main t:connect website. It is used to retrieve a CSV export of non-ControlIQ basal data, as well as bolus and IOB data. (I haven't found any mentions of bolus or IOB data in the Control:IQ-specific API.)
I have only tested tconnectsync with a Tandem pump set in the US Eastern timezone. Tandem's (to us, undocumented) APIs are [a bit loose with timezones](https://github.com/jwoglom/tconnectsync/blob/master/tconnectsync/parser.py#L15), so please let me know if you notice any timezone-related bugs.
## Backfilling t:connect Data
To backfill existing t:connect data in to Nightscout, you can use the `--start-date` and `--end-date` options. For example, the following will upload all t:connect data between January 1st and March 1st, 2020 to Nightscout: