https://github.com/benjamin-stefan/ant-plus-next
A modern Node.js library for interacting with ANT+ USB sticks and sensors. Supports both Node.js (USB) and WebUSB (browser) for heart rate monitors, speed sensors, and more.
https://github.com/benjamin-stefan/ant-plus-next
ant ant-plus ant-plus-next garmin usb webusb
Last synced: 2 months ago
JSON representation
A modern Node.js library for interacting with ANT+ USB sticks and sensors. Supports both Node.js (USB) and WebUSB (browser) for heart rate monitors, speed sensors, and more.
- Host: GitHub
- URL: https://github.com/benjamin-stefan/ant-plus-next
- Owner: Benjamin-Stefan
- License: mit
- Created: 2024-08-29T08:48:10.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-30T19:02:12.000Z (3 months ago)
- Last Synced: 2025-07-04T10:55:28.554Z (3 months ago)
- Topics: ant, ant-plus, ant-plus-next, garmin, usb, webusb
- Language: TypeScript
- Homepage:
- Size: 2.43 MB
- Stars: 7
- Watchers: 3
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# ant-plus-next
[](https://www.npmjs.com/package/ant-plus-next)
[](https://github.com/Benjamin-Stefan/ant-plus-next/actions/workflows/ci.yml)
[](https://github.com/Benjamin-Stefan/ant-plus-next/blob/main/LICENSE)
[](https://github.com/Benjamin-Stefan/ant-plus-next/issues)
A modern Node.js module for interacting with ANT+ USB sticks and sensors. It provides a user-friendly API for heart rate monitors, speed sensors, and more, supporting both Node.js USB and WebUSB (browser) for maximum flexibility in various environments.
## 🚀 Features
- 🖥️ Cross-platform: Supports Linux, Windows, macOS, and WebUSB (browser).
- 🔗 Node.js USB and WebUSB (browser) compatibility for a variety of environments.
- 🏃♂️ Easy interaction with heart rate, speed, and power sensors.
- 📦 Simple npm installation and intuitive API.
## 📋 Table of Contents
- [About](#about)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Migration from ant-plus](#migration-from-ant-plus)
- [Usage](#usage)
- [Important Notes](#important-notes)
- [API Documentation](#api-documentation)
- [Examples](#examples)
- [Contributing](#contributing)
- [License](#license)
## 🛠️ About
`ant-plus-next` is a versatile Node.js library designed for interacting with ANT+ USB sticks and sensors. The library supports **both Node.js (via USB)** and **WebUSB (browser)**, making it easy to integrate with devices like heart rate monitors, speed sensors, and power meters, whether you're building a server-side application or a browser-based solution.
With multi-platform compatibility (Linux, Windows, macOS, and browser), `ant-plus-next` allows seamless access to ANT+ sensor data, regardless of whether you're building a server-side application or an in-browser solution for data acquisition.
## 📦 Prerequisites
Before installing the module, ensure the following prerequisites are met:
### Linux
Make sure `libusb` is installed. You can install `libusb` and other required packages using:
```sh
sudo apt-get install build-essential libudev-dev
```
### WIndows
Use [Zadig](https://zadig.akeo.ie/) to install the WinUSB driver for your USB device. Otherwise, you will get `LIBUSB_ERROR_NOT_SUPPORTED` when attempting to open devices.
### macOS
Ensure that Garmin Express is not running, as it will attach to the ANT+ stick and prevent this module from accessing it.
### Browser (WebUSB)
To use WebUSB in a browser, ensure the following conditions are met:
- WebUSB is supported in **Google Chrome** (version 61 or higher) and other Chromium-based browsers like **Microsoft Edge**.
- WebUSB is **not supported in Firefox** or **Safari**.
- You must serve your web app over **HTTPS**, as WebUSB only works in secure contexts.
- Users must grant explicit access to the USB device using the browser's permission prompt.
## ⚙️ Installation
Install the module via npm:
```sh
npm install ant-plus-next
```
## 🔄 Migration from `ant-plus`
- Change variable `DeviceID` to `DeviceId`
- Renamed method `attach` to `attachSensor` in `BaseSensor`, `AntPlusBaseSensor`, `AntPlusScanner`, `AntPlusSensor`
- Update the constructor of `GarminStick2` and `GarminStick3` from `constructor(dbgLevel = 0)` to `debugOptions: DebugOptions = {}`.
- Change event `hbData` to `heartRateData` from Heart rate sensor
- Various other small, insignificant changes were made.
If you encounter any issues, please check the [Usage](#usage) or [Examples](#examples). If the problem persists, feel free to open an issue.
## 🚀 Usage
Here’s a quick guide to get you started with the `ant-plus-next` module:
### For Node.js
1. Create USB Stick Instance
```javascript
import * as Ant from "ant-plus-next";
const stick = new Ant.GarminStick3();
```
2. Create and configure a sensor:
```javascript
const heartRateSensor = new Ant.HeartRateSensor(stick);
```
3. Attach event listeners:
```javascript
heartRateSensor.on("heartRateData", (data) => {
console.log(`Device Id: ${data.DeviceId}, Heart Rate: ${data.ComputedHeartRate}`);
});
```
4. Open the USB stick and start scanning:
```javascript
stick.on("startup", () => {
heartRateSensor.attachSensor(0, 0);
});
const result = await stick.open();
if (!result) {
console.error("Stick not found!");
}
```
### For WebUSB (browser)
1. Create WebUSB Stick Instance
```javascript
import * as Ant from "ant-plus-next";
const webUsbStick = new Ant.WebUsbStick();
```
2. Create and configure a sensor:
```javascript
const heartRateSensor = new Ant.HeartRateSensor(webUsbStick);
```
3. Attach event listeners:
```javascript
heartRateSensor.on("heartRateData", (data) => {
console.log(`Device Id: ${data.DeviceId}, Heart Rate: ${data.ComputedHeartRate}`);
});
```
4. Open the WebUSB stick and start scanning:
```javascript
webUsbStick.on("startup", () => {
heartRateSensor.attachSensor(0, 0);
});
const result = await webUsbStick.open();
if (!result) {
console.error("WebUSB Stick not found!");
}
```
## ⚠️ Important Notes
- Never attach a sensor before receiving the `startup` event.
- Never attach a new sensor before receiving the `attached` or `detached` event of the previous sensor.
- Never detach a sensor before receiving the `attached` or `detached` event of the previous sensor.
## 📖 API Documentation
For detailed API documentation, visit the [TypeDoc-generated documentation](https://benjamin-stefan.github.io/ant-plus-next/).
## 🧪 Examples
Explore more examples in the [examples](/examples) folder.
### Example: Heart Rate Sensor for Node.js
```javascript
import * as Ant from "ant-plus-next";
const stick = new Ant.GarminStick3();
const heartRateSensor = new Ant.HeartRateSensor(stick);
heartRateSensor.on("heartRateData", (data) => {
console.log(`Device Id: ${data.DeviceId}, Heart Rate: ${data.ComputedHeartRate}`);
});
stick.on("startup", () => {
heartRateSensor.attachSensor(0, 0);
});
const result = await stick.open();
if (!result) {
console.error("Stick not found!");
}
```
### Example: Heart Rate Sensor for WebUSB (browser)
```javascript
import * as Ant from "ant-plus-next";
const webUsbStick = new Ant.WebUsbStick();
const heartRateSensor = new Ant.HeartRateSensor(webUsbStick);
heartRateSensor.on("heartRateData", (data) => {
console.log(`Device Id: ${data.DeviceId}, Heart Rate: ${data.ComputedHeartRate}`);
});
webUsbStick.on("startup", () => {
heartRateSensor.attachSensor(0, 0);
});
const result = await webUsbStick.open();
if (!result) {
console.error("WebUSB Stick not found!");
}
```
## 🤝 Contributing
Contributions are welcome! Please check out the [CONTRIBUTING.md](/CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](/CODE_OF_CONDUCT.md) for details.
## 📜 License and Acknowledgements
This project is licensed under the [MIT License](./LICENSE).
Parts of the code are based on the original project [ant-plus](https://github.com/Loghorn/ant-plus) by Alessandro Vergani (© 2015). The original project was also licensed under the MIT License.
### Thanks You!
Thanks to the original developers and all contributors!