{"id":15061541,"url":"https://github.com/osteele/imu-tools","last_synced_at":"2025-04-10T08:58:58.656Z","repository":{"id":36349861,"uuid":"201946091","full_name":"osteele/imu-tools","owner":"osteele","description":"Send sensor data from an ESP + BNO055 → MQTT and/or serial port","archived":false,"fork":false,"pushed_at":"2022-04-17T14:51:31.000Z","size":870,"stargazers_count":17,"open_issues_count":5,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-02T20:05:17.368Z","etag":null,"topics":["bno055","esp","esp32","esp8266","imu-sensor","micropython","mqtt","physical-computing"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/osteele.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-08-12T14:25:33.000Z","updated_at":"2025-02-01T13:32:17.000Z","dependencies_parsed_at":"2022-08-25T04:11:33.558Z","dependency_job_id":null,"html_url":"https://github.com/osteele/imu-tools","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osteele%2Fimu-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osteele%2Fimu-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osteele%2Fimu-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osteele%2Fimu-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/osteele","download_url":"https://codeload.github.com/osteele/imu-tools/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247828823,"owners_count":21002975,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bno055","esp","esp32","esp8266","imu-sensor","micropython","mqtt","physical-computing"],"created_at":"2024-09-24T23:21:01.249Z","updated_at":"2025-04-10T08:58:58.636Z","avatar_url":"https://github.com/osteele.png","language":"Python","readme":"# IMU Tools\n\nThis project contains tools for sending IMU data over a WiFi or Bluetooth\nconnection from an ESP, and consuming it in a web page.\n\nit contains these components:\n\n- A MicroPython program (in `./pyboard`) that runs on an ESP8266 or ESP32. It\n  publishes sensor data from a connected to BNO055 IMU, a simulated IMU, to an\n  MQTT connection, or the serial port.\n\n- Web pages (in the `web` directory) that display IMU data as graphs, charts,\n  and 3D models using React, p5.js, Highcharts, and D3. These serve as examples\n  of how to consume the IMU data.\n\n- A fleet management dashboard (also in the `web` directory) that displays a\n  list of connected device, with frame rates.\n\n- Command-line tools (in the `scripts` directory, and invoked via `poetry`)\n  to report, simulate, and measure the sample rate of IMU data, and relay it to\n  a named port.\n\n- Additional command-line scripts for managing MicroPython/ESP development.\n\n- An npm package [imu-tools npm\n  package](https://www.npmjs.com/package/imu-tools) that that can be included in\n  a web page in order to subscribe to an MQTT broker that is relaying data in\n  the **format** provided by the tools in this directory.\n\n- An experimental demonstration of rigging a Blender model to IMU output.\n\nThe ESP program in this repository sends data over MQTT/WiFi. The rest of the\ncode in this repository is also designed to work\\ with\n\u003chttps://github.com/osteele/Arduino-BLE-IMU\u003e, which uses Bluetooth Low Energy\n(BLE) connection instead.\n\n## Modes of Operation\n\n![Diagram of connection to local MQTT](docs/img/local-mqtt.png) Local MQTT\nGateway. An ESP32 connects via WiFi to an MQTT broker running on a developer\nlaptop. A web app, such as a React or p5.js application, can connect to this\nbroker to read the sensor data from all the IMUs on the network.\n\n![Diagram of two IMUs connected to a single MQTT\nbroker](docs/img/2providers.png). This architecture MQTT Gateway allows a web\npage to draw information from many MCUs.\n\n![Diagram of two computers connected to a single MQTT\nbroker](docs/img/2consumers.png). It also allows several computers to subscribe\nto data from the same sensors. This is useful for an installation.\n\n![Diagram of the MQTT broker running on its own node](docs/img/cloud-mqtt.png).\nRemote MQTT Gateway. The same as above, but the MQTT gateway can run on a server\nwith greater availability than a laptop. This has the advantage that multiple\nlaptops can all subscribe to data from a fleet of sensors. It has the\ndisadvantage that the development machine must be on the same LAN as the MQTT\nbroker, or it must be remote for less security and greater latency than a local\ndeployment.\n\n![Diagram of Bluetooth connection](docs/img/ble.png). Alternate ESP firmware, in\n\u003chttps://github.com/osteele/Arduino-BLE-IMU\u003e, which publishes sensor data via\nBLE instead of MQTT. This permits use at lower power levels, without WIFi, and\nwithout the need for an MQTT broker.\n\nCurrently, only the Chrome browser supports Web Bluetooth; and, the user has to\nmanually initiate each BLE connection each time the page is reloaded. This is a\nbother during development, and when working multiple devices. As a workaround,\nthe system can also be used in the mode:\n\n![Diagram of Bluetooth to MQTT relay](docs/img/ble-relay.png). The BLE -\u003e MQTT\nRelay is a command-line application that connects as a Central BLE device to IMU\nBLE Peripherals, and relays their sensor data to a (local or remote) MQTT\nbroker.\n\nThe Serial -\u003e MQTT Gateway that publishes information from an MCU that is\nconnected to a computer's serial port, to a local or remote MQTT broker.\n\n## Installation\n\n1. Clone this repo.\n\n2. Install [poetry](https://python-poetry.org/docs/#installation). On macOS\n   running Homebrew, you can also install it via `brew install poetry`.\n\n3. Run `poetry install`\n\n4. Install RabibitMQ, or find a RabbitMQ broker. Either: (1) Follow the\n   instructions\n   [here](https://www.notion.so/RabbitMQ-7fd3ba693d924e1e893377f719bb5f14) to\n   install RabbitMQ on your computer; or (2) get an MQTT hostname, username, and\n   password from your instructor, and use it in the instructions below.\n\n## Flashing the ESP\n\n1. Download a GENERIC image from [MicroPython Downloads](https://micropython.org/download#esp32).\n   For example, `esp32-idf3-20191220-v1.12.bin`.\n\n2. Flash the ESP. If you downloaded the image to\n   `images/esp32-idf3-20191220-v1.12.bin`, then run:\n\n   ```sh\n   ./scripts/flash images/esp32-idf3-20191220-v1.12.bin\n   ```\n\n3. Upload the Python source code to the ESP. In a terminal window in this\n   directory, run:\n\n   ```sh\n   ./scripts/py-upload\n   ```\n\n## Viewing the Web Examples\n\nRun `./scripts/webserver` to start a web server.\n\n\u003chttp://127.0.0.1:8000\u003e displays a directory of web pages in the `web` directory\ndirectory.\n\n\u003chttp://127.0.0.1:8000/barchart.html\u003e displays a live bar chart of sensor data.\n\n\u003chttp://127.0.0.1:8000/chart.html\u003e uses HighCharts to display another live\ngraph, that automatically scales the y axis as data arrives.\n\n\u003chttp://localhost:8000/3d-model.html\u003e displays the bunny, with its orientation\nyolked to the IMU orientation. The model is red before the sensor is minimally\ncalibrated, and it fades out when sensor data is not being received.\n\n## Bluetooth\n\n\u003chttps://github.com/osteele/Arduino-BLE-IMU\u003e is an alternative to the\nMicroPython program in `./pyboard`, that sends IMU data over a Bluetooth Low\nEnergy (BLE) connection instead of MQTT.\n\nFollow the instructions in that repository to upload it to an ESP32.\n\nThere are two means of using this data:\n\n1. In a [browser that supports Bluetooth](https://caniuse.com/web-bluetooth)\n   (e.g. Chrome or Edge; not Safari or Firefox). In Chrome, any of the demos (or\n   a program that uses the imu-tools npm package) will include a “Connect\n   Bluetooth\" button. Clicking on this button opens the browser's Bluetooth\n   connection dialog. The button disappears once a device has been connected;\n   press the `b` key to bring up the connection dialog in order to connect to a\n   second (and third, etc.) device.\n2. Run the BLE-\u003eMQTT gateway.\n   1. Once: in the command line, run `npm install`.\n   2. Each time you start a development session: run `npm run ble2mqtt`.\n\n## Command-Line Testing\n\n`poetry run sub` runs an MQTT client that subscribes to IMU messages that are\nsent to the MQTT broker, and relays them to the terminal.\n\n`poetry run pub` publishes an MQTT message. The message is a simulated sensor\nsample.\n\n`./scripts/simulate` simulates a device. It continuously publish messages from a\nsimulated IMU until the user kills (^C) the script. (This is the same as the\n`--continuous` option to `poetry run pub`.) The simulated sensor readings change\nover time.\n\n`./scripts/simulate --help` gives a list of command-line options. Use\n`--device-id` to simulate a particular ID; you can use this to run multiple\nsimulations, in different terminals, with different ids.\n\n## MicroPython development\n\n`./scripts/py-upload` copies the code in `pyboard` to the attached ESP, and then\nreboots the board.\n\n`./scripts/py-repl` opens an [rshell](https://github.com/dhylands/rshell#rshell)\nREPL to the attached ESP. Press `⌃X` to exit the `./scripts/py-repl` command.\n\n`./scripts/serial-term` is an alternative to `./scripts/py-repl`, that uses the\n[GNU `screen` command](https://www.gnu.org/software/screen/) instead of\n`rshell`. `serial-term` connects to the board more quickly than `py-repl`.\nConsult the documentation for `screen` to see how to exit this command.\n\n[MicroPython Development\nNotes](https://paper.dropbox.com/doc/MicroPython-Development--Ai1pmnXzhBdkxZ6SuEPMTDiDAg-sAf2oqgmH5yIbmx27kZqs)\ncontains notes on developing MicroPython on the ESP.\n\nWhile running a REPL on the board, press `⌃D` to reboot the board. (`⌃` is the\ncontrol character. Hold it down while the `D` is pressed, and then release them\nboth.)\n\n## Blender\n\nAs a proof of concept, IMU data can be used to control the orientation of a\nrigged joint in Blender.\n\nIn a terminal, run: `./scripts/mqtt2pipe`\n\nIn another terminal, launch Blender with the `--python blender/motion.py` option:\n\n`/Applications/Blender.app/Contents/MacOS/Blender model.blend --python blender/motion.py`\n\nNote: If the pipe buffer fills (for example, because Blender is closed), the\n`mqtt-sub` process will hang. You will need to force quit it (^C) and launch it\nagain.\n\n## Firmware Operation\n\nAn ESP that is running the firmware in this directory connects to a WiFi network\nand an MQTT broker, and continuously publishes MQTT messages to the\n`imu/${device_id}` topic, where `${device_id}` is a unique device id for the\nESP. (It is currently the lowercase hexadecimal representation of the device's\nMAC address.) The message payload is a JSON string with properties whose names\nare the values of the IMU sensors, fused data, and other data: accelerometer,\ngyroscope, magnetometer, euler, quaternion, calibration, temperature. The\nmessage also includes a \"timestamp\" value, which is the millisecond counter.\nThis can be used to compute the relative time between samples.\n\nIt periodically prints the sample rate to the serial port.\n\nIt can optionally be configured to instead send the sensor data.\n\nThe serial port format is compatible with\n[osteele/microbit-sensor-relay](https://github.com/osteele/microbit-sensor-relay).\n\n## References\n\n- [Paho MQTT](https://pypi.org/project/paho-mqtt/)\n- [MicroPython](http://docs.micropython.org/en/latest/)\n- [MicroPython MQTT](https://github.com/micropython/micropython-lib/tree/master/umqtt.simple)\n\n## Credits\n\n`BNO055.py` and `functools.py` are adapted from Radomir Dopieralski's\n[`deshipu/micropython-bno055`](https://github.com/deshipu/micropython-bno055).\n\nThis uses [MicroPython](https://micropython.org) and Paho MQTT, and uses\n[rshell](https://github.com/dhylands/rshell).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fosteele%2Fimu-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fosteele%2Fimu-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fosteele%2Fimu-tools/lists"}