Vivian

Vivian is free, open source software for communicating with the 4iiii Viiiiva heart rate monitor over Bluetooth LE. In particular, it allows the user to download the Viiiiva's .FIT activity logs without using the official 4iiii app.

This software is Copyright Dean Scarff, 2020. It is licensed under the Apache License, Version 2.0.

Vivian is not endorsed by 4iiii. It has been tested with a Viiiiva running firmware version 2.0.0; whether it works with other versions or devices is unknown.

Vivian does not expose generic Bluetooth heart rate monitor (HRM) functionality: you can't use it for realtime heart rate or RRI monitoring. There are many other fitness apps that can be used for realtime monitoring.

Currently, the sole end-user product of the Vivian project is vivtool, a macOS command-line interface for listing and downloading .FIT activity logs from a Viiiiva heart rate monitor.

Usage

vivtool is a command-line interface, which means you must run the program from macOS's Terminal.app or similar terminal software.

List all activity logs on the Viiiiva:

$ vivtool ls -l -h
650 bytes       2020-09-20, 12:12       0001.fit
614 bytes       2020-09-20, 05:12       0002.fit
471 bytes       2020-09-19, 12:44       0003.fit

Copy an activity log from the Viiiiva to the current directory:

$ vivtool cp 0001.fit ./

Remove an activity log from the Viiiiva:

$ vivtool rm 0001.fit

Synchronize the Viiiiva's internal clock:

$ vivtool date -h -s now
2020-10-31, 12:57

For a complete reference, consult the manual page:

$ man vivtool

Installation

The vivtool command requires macOS 11.0 (Big Sur) or later to run. Choose one of the options for installation below.

Homebrew

The vivtool command can be installed using Homebrew with a custom tap:

brew install --HEAD p00ya/tap/vivtool

Github releases

A precompiled binary can be downloaded from the github releases page. To download, extract, and authorize the executable to run, run these commands:

curl -LO https://github.com/p00ya/vivian/releases/latest/download/vivtool.tar.xz
tar -xf vivtool.tar.xz --strip-components 1
xattr -d com.apple.quarantine bin/vivtool
codesign -f -s "-" -v bin/vivtool

The last two commands remove the quarantine flag and sign the executable for local use. Without these extra steps, macOS's "Gatekeeper" system will pop up a dialog saying "vivtool cannot be opened because the developer cannot be verified" or "vivtool cannot be opened because Apple cannot check it for malicious software".

The files can then be copied to system paths:

install -p bin/vivtool /usr/local/bin/
install -d /usr/local/share/man/man1/
install -p share/man/man1/vivtool.1 /usr/local/share/man/man1/

Installation from source

You can clone the git repository and build the project with Swift. It will require Swift 5.5 to be installed (other Swift versions may work but have not been tested). Swift 5.5 in installed as part of Xcode 13.

git clone https://github.com/p00ya/vivian.git
cd vivian
./install.sh

The install.sh script will install the executable and manual page in the /usr/local hierarchy if you have permission to write to that directory. Alternatively, you can set the DSTROOT environment variable when calling install.sh to stage it elsewhere.

Technical Design

Background

The Viiiiva supports "Activity Logging", which allows sensor data to be stored on the device in an activity log when no Bluetooth device is connected. Later, the activity logs may be downloaded as .FIT files over Bluetooth.

4iiii's apps download the .FIT files using a non-standard Bluetooth GATT characteristic with service UUID 5b774111d5267b9a4ae7e59d015d79ed (5B774111-D526-7B9A-4AE7-E59D015D79ED). The GATT characteristic is used as a transport for a non-standard protocol resembling ANT-FS. Fitness apps relying on the standard Bluetooth Heart Rate Service cannot download the Viiiiva's activity logs.

Design Goals

The goals for the project are to build:

1. A command-line app for power users (including the author) to retrieve activity logs on macOS.
2. A software library that will allow other developers to write their own apps that utilize Viiiiva's non-standard protocol.
3. A desktop app to allow end-users to download activity logs from their Viiiiva.

Currently the first two goals have been met, and the desktop app is on hold.

Building

Test and build from the command line:

cd vivtool
swift package clean
swift test
swift build

Overview

There are two main components to the project:

• libviv, a software library that allows other developers to write their own apps that utilize Viiiiva's non-standard protocol.
• vivtool, a macOS command-line utility for downloading .FIT activity logs from a Viiiiva without using the official 4iiii app.