This is an Electron App that acts as an uploader client for Tidepool. It is intended to allow you to plug diabetes devices into your computer's USB port, read the data stored on them, and upload a standardized version of the data to the Tidepool cloud.
This README is focused on just the details of getting the uploader running locally. For more detailed information aimed at those working on the development of the uploader, please see the developer guide.
- Clone this repository.
- Make sure you have node v16.x installed. If you are managing node installations with
nvm
, which we highly recommend, you can just donvm use
when navigating to this repository to switch to the correct version of node. (In this repository, the correct version of node will always be the version of node packaged by the version of Electron that we are using and specified in the.nvmrc
file.) - Run
npm install
or, preferably,yarn
- Set the config for the environment you want to target (see Config below)
- Run the following command:
$ npm run dev
or
$ yarn dev
(This will bundle the application with webpack and watch for changes. When it stops printing output you can continue to the next step.)
NB: React components and CSS will hot load after changes (this can be confirmed by watching the JavaScript console), but changes to device drivers and other code outside of the React components will not - use 'Reload' to reload after such changes. If the compilation/hot reload of a component fails for any reason (e.g. from a syntax error) you may need to reinitialize the hot loader by reloading the application.
If you are running Linux you probably need to be using an Ubuntu distribution or derivative. To get around this for other distrubutions you can try to build a local docker image which is based on Ubuntu 18.04 and use the yarn/npm commands interactively.
NOTE: You need to add udev rules to your host for uploads to actually work. You can find the udev rules here. The file should be placed in /etc/udev/rules.d/
and the host should be rebooted.
-
Build the image
docker-compose build
-
Run it
docker-compose up -d
-
Work with it interactively.
Even if you kill the Tidepool Uploader GUI the container will continue to run. You can work with the yarn commands like you would locally by using docker exec.
Examples
Interactively select the yarn target:
docker exec -it uploader bash -c "yarn run"
Rebuild:
docker exec -it uploader bash -c "yarn build"
Start the Dev GUI:
docker exec -it uploader bash -c "yarn dev"
Configuration values (for example the URL of the Tidepool Platform) are set via environment variables. If you need to add a config value, modify the .config.js
file. If you need to read a config value inside the app, use var config = require('./lib/config')
. To set config values (do this before building the app), you can use Shell scripts that export environment variables (see config/local.sh for an example that exports the appropriate variables when running the whole Tidepool platform locally using runservers), for example:
$ source config/local.sh
$ yarn start
For ease of development we have several debug features that developers can turn on and off at will (and to suit various development use cases, such as working on a new device driver versus working on the app's UI). Each of these debug features is set with an environment variable, but rather than being loaded through .config.js
(as we do for production configuration variables, see above), we load these through the webpack DefinePlugin
(see Pete Hunt's webpack-howto for an example, although note Hunt uses the term 'feature flag').
The environment variable DEBUG_ERROR
(boolean) controls whether or not errors sourced in device drivers are caught and an error message displayed in the UI (the production setting) or whether they are thrown in the console (much more useful for local development because then the file name and line number of the error are easily accessible, along with a stack trace). DEBUG_ERROR
mode is turned on by default in config/device-debug.sh
.
This can also be toggled internally in the running Electron app via a right-click context menu available on the login screen, much like the menu for switching environments.
All debug options are turned off by default in config/local.sh
.
To run the tests in this repository as they are run on CircleCI use:
$ yarn test
or
$ yarn test
We use ESLint to lint our JavaScript code. We try to use the same linting options across all our client apps, but there are a few exceptions in this application, noted with comments in the .eslintrc
configuration file.
To run the linter (which also runs on CircleCI with every push, along with npm test
), use:
$ npm run lint
Aside from the (fairly minimal) JavaScript code style options we enforce through the linter, we ask that internal developers and external contributors try to match the style of the code in each module being modified. New modules should look to similar modules for style guidance. In React component code, use existing ES6/ES2015 components (not legacy ES5 components) as the style model for new components.
NB: Please keep ES5 and ES6/ES2015 code distinct. Do NOT use ES6/ES2105 features in ES5 modules (most easily recognizable by the use of require
rather than import
).
Docs reside in several places in this repository, such as docs/
and lib/drivers/docs
. They are built as a static site with GitBook and served at developer.tidepool.org via GitHub Pages.
See this guidance on our use of GitBook at Tidepool.
This section is Tidepool-specific. Release management and application updates are handled via the Github provider in the electron-builder
project. The recommended workflow for a new production release is as follows:
- When you're working on what might become a new release, increment the version number in
package.json
andapp/package.json
and commit/push (on the branch) - The CI server will create a draft release in Github with the title of the version from the
package.json
file and will automatically attach the distribution artifacts to that draft (drafts are not publicly visible) - When your pull request is approved and merged to
master
, go to the draft release and type in the version for the tag name, ensure that you're targeting themaster
branch, fill out the release notes and publish the release. This will create the tag for you.
For a non-production release (alpha, dev, etc.)
- Increment the version number in
package.json
andapp/package.json
and ensure that you have included the channel information after the version patch number (i.e.v0.304.0-alpha
orv0.304.0-beta.2
). The hyphen separated version semantic is important. - The CI server(s) will create a draft release in Github with the title of the version from the
package.json
file and will automatically attach the distribution artifacts to that draft (drafts are not publicly visible) - When you want to publish your non-production release, go to your draft and type in the version for the tag name, ensure that you're targeting the branch that you're currently releasing from, mark the release as a
pre-release
, fill out the release notes and publish the release. This will create the tag for you on the branch that you want.
The Uploader has a self-update mechanism that will look at the latest release and compare versions, downloading and prompting the user to update if a newer version is available. For production releases, only official releases will be considered. For non-production releases (-alpha
, -beta.2
, etc.) releases marked as pre-release
will also be checked, matching against the string portion of the post-hyphen version segment. For more detail about this behavior see the electron-builder docs concerning auto-update options
We use the following environment variables on the CI server:
Variable | OS Image | Use |
---|---|---|
APPLEID | MacOS | Notarization |
APPLEIDPASS | MacOS | Notarization |
TEAMID | MacOS | Notarization |
AWS_ACCESS_KEY_ID | Both | S3 builds and AV e-mails |
AWS_SECRET_ACESS_KEY | Both | S3 builds and AV e-mails |
CSC_FOR_PULL_REQUEST | Both | true , code signing for PR |
CSC_KEY_PASSWORD | MacOS | Certificate password |
CSC_LINK | MacOS | Code signing certificate |
WIN_CSC_KEY_PASSWORD | Windows | Certificate password |
WIN_CSC_LINK | Windows | Code signing certificate |
DEBUG | MacOS | Set to electron-builder |
GH_TOKEN | Both | For GitHub builds |
PUBLISH_FOR_PULL_REQUEST | Both | true , build artefact for PR |
ROLLBAR_POST_TOKEN | Both | Rollbar logging |
FTP_AV_PASSWORD_TIDEPOOL | Windows | AV submission |
Atom
apm install editorconfig es6-javascript javascript-snippets linter linter-eslint language-babel autocomplete-modules file-icons
Sublime
- Editorconfig Integration
- Linting
- ESLint Integration
- Syntax Highlighting
- Autocompletion
- Node Snippets
- ES6 Snippets
Others
- Editorconfig
- ESLint
- Babel Syntax Plugin
- OS X: Cmd Alt I or F12
- Linux: Ctrl Shift I or F12
- Windows: Ctrl Shift I or F12
See electron-debug for more information.
This project includes the following DevTools extensions:
- Devtron - Install via electron-debug.
- React Developer Tools - Install via electron-devtools-installer.
- Redux DevTools - Install via electron-devtools-installer.
You can find the tabs on Chrome DevTools.
If you want to update extensions version, please set UPGRADE_EXTENSIONS
env, just run:
$ UPGRADE_EXTENSIONS=1 npm run dev
# For Windows
$ set UPGRADE_EXTENSIONS=1 && npm run dev
All .module.less
files will be use css-modules.
To package apps for the local platform:
$ npm run package
$ yarn package
To package apps with options:
$ npm run package -- --[option]
To package the app on your local machine, you need to set the ROLLBAR_POST_TOKEN
environment variable to send telemetry data to Rollbar. You can get one for free from https://rollbar.com
macOS: To notarize the app so that it will run on macOS Mojave, you need to set the environment variables APPLEID
, APPLEIDPASS
, and TEAMID
. Note that you need to set an app-specific password in https://appleid.apple.com for this to work.
Note that you'll need to build Windows builds on a Windows machine, and MacOS builds on a Mac.
To run the application without packaging run
$ npm run build
$ npm start
To run End-to-End Test
$ npm run build
$ npm run test-e2e
See electron-builder CLI Usage
This project uses a two package.json structure.
- If the module is native to a platform or otherwise should be included with the published package (i.e. bcrypt, openbci), it should be listed under
dependencies
in./app/package.json
. - If a module is
import
ed by another module, include it independencies
in./package.json
. See this ESLint rule. - Otherwise, modules used for building, testing and debugging should be included in
devDependencies
in./package.json
.
Tidepool Uploader makes use of the following LGPL-licensed libraries:
- libmtp (http://libmtp.sourceforge.net/)
- LZO implementation in libavutil, which is part of FFmpeg (https://github.com/FFmpeg/FFmpeg/tree/master/libavutil)
These libraries are used in the following Node.js modules created by Tidepool and are dependencies of the Tidepool Uploader:
- https://github.com/tidepool-org/node-mtp (libmtp)
- https://github.com/tidepool-org/lzo-wasm (libavutil)
The LGPL is intended to allow use of libraries in applications that don’t necessarily distribute the source of the application. The LGPL has two requirements:
- users must have access to the source code of the library
- users can make use of modified versions of the library
To satisfy (1) we provide links to the relevant code repositories. To satisfy (2) we dynamically link to the library, so that it’s possible to swap it out for another version of the library.
Compile FFmpeg ourselves to ensure that we’re using the LGPL version and only include the minimal set of libraries
Use dynamic linking (e.g. on Windows this means using a .dll, and on MacOS a .dylib) when linking to these libraries
Mention that the software uses libraries from the FFmpeg project and libmtp under the LGPLv3, e.g. This software uses code of <a href=http://ffmpeg.org>FFmpeg</a> and <a href=”http://libmtp.sourceforge.net/”>libmtp</a> licensed under the <a href=a href=https://www.gnu.org/licenses/lgpl.html>LGPLv3</a> and its source can be downloaded <a href=”https://github.com/FFmpeg/FFmpeg/tree/master/libavutil”>here</a> and <a href=”https://sourceforge.net/projects/libmtp/”>here</a>
If your EULA claims ownership over the code, you have to explicitly mention that you do not own FFmpeg or libmtp, and where the relevant owners can be found.
- LGPL v3 License Text (on gnu.org)
- LGPL on Wikipedia