Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/grimsteel/miband4-web

A web interface for the Mi Smart Band 4 that respects your privacy
https://github.com/grimsteel/miband4-web

bluetooth-low-energy miband miband4 progressive-web-app web-bluetooth

Last synced: 9 days ago
JSON representation

A web interface for the Mi Smart Band 4 that respects your privacy

Host: GitHub
URL: https://github.com/grimsteel/miband4-web
Owner: grimsteel
License: gpl-3.0
Created: 2023-03-12T06:10:02.000Z (over 1 year ago)
Default Branch: main
Last Pushed: 2024-06-21T20:44:14.000Z (5 months ago)
Last Synced: 2024-06-22T12:28:30.576Z (5 months ago)
Topics: bluetooth-low-energy, miband, miband4, progressive-web-app, web-bluetooth
Language: Vue
Homepage: https://miband4.web.app
Size: 488 KB
Stars: 9
Watchers: 1
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

# Mi Band 4 Web

A web interface for the Mi Smart Band 4 that respects your privacy.

Before you begin using it, you'll need your Mi Band 4's:

* Bluetooth MAC Address. This can be found by going to More > Settings > About on your band
* [Authentication Key](https://codeberg.org/Freeyourgadget/Gadgetbridge/wiki/Huami-Server-Pairing).
Note that this requires you to have previously created a Mi Fit account and paired your band with Mi Fit

This project is based off of [Satkar Dhakal's miband4](https://github.com/satcar77/miband4) which is licensed under the MIT license. It would not have been possible without the work there.

## Features:

✅: Complete

🕑: In Progress

❌: Not Started (but planned)

¹ Websites can't access what music you're playing, so you can only set what the band's music screen displays manually and see when the buttons are tapped.

² This includes band location, lift wrist to wake, night mode, and band lock.

## Reauthorization of Bluetooth Devices

### API Structure:

The only method for gaining permission to access a device is the `requestDevice` method. This shows a popup to the user for selecting a device. It does not allow the developer to filter by mac address or device ID.

#### Authorization "sessions":

When the user grants a website access to a device (with requestDevice), the website will be able to access that device as long as it keeps the corresponding `BluetoothDevice` in memory. (However, these are NOT structured cloneable, so we can't put them in IDB) This means that the user will need to "reauthenticate" the device (a new authentication session) on different tabs or when they refresh the page.

However, if the user enabled Web Bluetooth Persistent Permissions, the `BluetoothDevice` object will be persisted across tabs, refreshes, and browser restarts. This means that the user will only need to reauthenticate the device if they manually revoke the permission.

#### Device ID:

The device ID is a unique identifier for a device generated by the browser. It is not the same as the MAC address. _A new one is regenerated for every authentication session_. This means that we can't reliably identify a device based on its device ID.

### How we do it:

When a user requests a device with `requestDevice`, we store the device ID and MAC address in IDB. The primary key, however, is an incrementing integer. This is because we can't use the device ID as a primary key, since it is regenerated for every authentication session. **We also keep the BluetoothDevice in memory**

When a user opens a device, with our `id` primary key, we have to now obtain the corresponding `BluetoothDevice`

### Without persistent permissions:

When a user tries to open this device on the same tab that it was authorized in, we should have the corresponding device in memory, so we just try to find the correct device based on the device ID stored in Indexed DB.

> **Note**
> If the device ID stored in IDB changed (if the user reauthorized from another tab), then we won't be able to find the correct device. In this case, we will have to reauthorize the device.

When a user tries to open the device on another tab, or after refreshing/restarting the browser, we won't have the corresponding device in memory. In this case, we will have to reauthorize the device. This involves asking the user to select the correct device from the `requestDevice` popup. We then check that its correct by comparing the MAC address stored in IDB with the MAC address of the device that the user selected. (We can get the MAC address by reading a characteristic).

Once reauthorized, we store the new device ID in IDB, **just in case it changed**, and keep the new `BluetoothDevice` in memory.

### With persistent permissions:

We can detect that persistent permissions is enabled if the `getDevices` method exists.

When a user tries to open a device, we check to see if any of the devices returned by `getDevices` have the same device ID as the one stored in IDB. If it does, we return that device. If it doesn't, we reauthorize the device.

## Roadblocks Encountered

* `BluetoothDevice` objects are not structured cloneable. This means that we can't put them in IDB.
* Bluetooth Device IDs are randomly generated for every authentication session. This means that we can't reliably identify a device based on its device ID.
* TONS of errors can be encountered when connecting to devices. Reauthorization is the most reliable way 😑

## Bugs you should star:

* [Paired devices always created as BT Classic, but could be BLE](https://crbug.com/630581)
* [Implement watchAdvertisments](https://crbug.com/654897)
* [Get permitted devices](https://crbug.com/577953)
* [Implement Persistent Web Bluetooth Permissions](https://crbug.com/974879)
* [Bluetooth Device is no longer in range](https://crbug.com/1173186)