Pulse

Simple Heartbeat Monitor :heart: :bar_chart:

Pulse is a heartbeat monitor; it connects with your smart band and fetches your pulse in real-time to display it on a dashboard. It currently supports MiBand 2 and 3, but support for more devices can be added.

This readme only contains the technical details about the project; the journal for this project can be found here with more information on design decisions, applications etc.

See the demo gif here.

Index

• About
• Usage
  • Pre-Requisites
  • Development Environment
  • File Structure
  • Commands
• Contribution
• FAQ
• Acknowledgment
• License

About

There are 3 main services:

1. pulse
2. pulseExplorer
3. mibandPulse

pulse

This service act as a stub for other services and as a server for the users. It serves the frontend which is compiled with its binary using pkger. It starts with after the pulseExplorer service and waits for 5 seconds before starting, to allow pulseExplorer to fetch devices, and after that, it fetches the list of Bluetooth devices and stores them in a state to send it to frontend when requested. Once the user requests to connect their band, the request is sent to mibandPulse as that is the only device currently supported. Then mibandPulse connects to that device and streams real-time heartbeats to pulse.

If you want to know why it is designed this way, you might want to check out this blog.

pulseExplorer

pulseExplorer use bettercap/gatt(Fork of paypal/gatt package), which is designed to be embedded and required Sudo access. It only runs for 8 seconds and scans all the devices in the area and stream them via gRPC server.

mibandPulse

mibandPulse use yogeshojha/MiBand3 package to connect to MiBand and stream them to pulse using gRPC. It is converted into shared objects(so) file using Cython to optimise the speed.

Usage

Pulse can be deployed on a Raspberry Pi, and some services under this project can also be embedded. To run it on your system, you can use the makefile. Assuming that you have already set up the development environment, you can use following commands to build and run this project.

$ make setup # Install dependencies.
$ make tools # Compile python to .so and install the command on the system.
$ make run # Install and run the project.

Here, make tools build and install the mibandPulse package in your pip, This is because the author wanted it to be easily exportable as a single .whl file and use it as a command. If you want to remove the package, you can directly remove it using pip uninstall mibandPulse, or you can use make uninstall.

Pulse has not been tested on raspberry pi and any other system other than on Arch. However, it is expected to run on other platforms with minimum efforts.

Pre-Requisities

This pre-requisites are not necessarily for running the project, but if you plan to use or contribute to this project or play with the source code, knowledge of following things is recommended.

• Golang
• Cython
• ReactJS/NextJS
• Socket.io
• gRPC

Development Environment

To develop or build this project, make sure you have the following environment setup:

• Install, and setup Go environment.
• Install python.
• Install NodeJS and yarn.
• Install Make.
• Clone this project in your workspace.

Once you have set up the above environment, we will use make to install dependencies. Go to the root of the project and run the following command; it installs all the node modules, Python and Go dependencies.

$ make setup

File Structure

The file structure of this project follows the conventional standard, so it should be reasonably easy to understand. A description is given below:

Folder/File Name	Description
/api	Protocol Definition.
/cmd	Main applications for this project. Home for pulse and pulseExplorer services.
/internal	Private application code, it doesn’t exported by Go. See release note. Contains gRPC generated and other files.
/resources	Resources used for readme or public.
/tools	Supporting tools for this project. Holds mibandPulse service.
/web	Web application used by pulse.
/bin	Binary and build files.

Commands

build                          Build pulse and pulseExplorer command
clean                          Remove all the build files
dev                            Start the development environment to test
grpc                           Build files based on api proto files
help                           Display help screen
install                        Build and install pulse pulseExplorer command
pkger                          Compile web files in a package using pkger
run                            Run the project
setup                          Setup dev environment
tools                          Compile and install the miband library
uninstall                      Uninstall the mibandPulse command
web                            Build web files

Contribution

Your contributions are always welcome and appreciated. Following are the things you can do to contribute to this project.

1. Report a bug.
2. Request a feature.
3. Create a pull request.

:sparkles: It takes time and efforts to think, design and develops open-source projects, so If you like this project, do star it so contributors can know you appreciate their efforts. :)

If you are new to open-source, make sure to check read more about it here and learn more about creating a pull request here.

FAQ

Q.) I want to use this project for a commercial purpose?

Great! Yes, you can! :tada: However, it will be appreciated that you reach out to the author and let him know. It will be nice to see it being applied in the real world, and maybe the author can decide to get involved with your endeavours.

Q.) I want to know how and why this project was created?

You can refer to this blog.

Q.) Can I add support for more devices and how?

Yes! You will need to create/add a service to /tools for it and in pulse identify the device using the Manufacturer code and send the request to the service for that device.

Troubleshoot

If you are going to use or develop this project, the following are a few things which might help you fix some of the known troubles.

• When testing with yarn dev and pulse, you will need to enable CORS, as the dev frontend server run on 7001 and pulse command use 7000, the socketio connection won’t be established otherwise.
• When testing mibuildPulse, you might have to remove the milib.XXX references manually from files and add it back when you are ready to build it or commit it. I know this is not how it should be, but I didn’t get time to fix this.

Acknowledgment

• Logo made by Trinh Ho from www.flaticon.com
• Diagram created using draw.io
• gRPC endpoints tested using BloomRPC

License

MIT License

Copyright (c) 2020 Raman Tehlan

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.