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.
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
The vivtool command requires macOS 11.0 (Big Sur) or later to run. Choose one of the options for installation below.
The vivtool command can be installed using Homebrew with a custom tap:
brew install --HEAD p00ya/tap/vivtool
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/
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.