Add module pre-compile to fix some import errors

.github/workflows/pre-compile.yml

@@ -0,0 +1,83 @@
+# This workflow will pre-compile the module using mpy-cross
+
+# To test with act:
+# act -j precompile-v5 -s GITHUB_TOKEN=GH_token --artifact-server-path artifacts_v5
+# act -j precompile-v6 -s GITHUB_TOKEN=GH_token --artifact-server-path artifacts_v6
+
+name: Pre-compile modules
+
+on:
+ push:
+
+jobs:
+ precompile-v5:
+ runs-on: ubuntu-latest
+
+ steps:
+ - uses: actions/checkout@v3
+ with:
+ path: max30102
+
+ - uses: actions/checkout@v3
+ with:
+ repository: 'micropython/micropython'
+ path: micropython
+
+ - name: Set up Python
+ uses: actions/setup-python@v3
+ with:
+ python-version: '3.8'
+
+ # For MicroPython version <1.19, compile with mpy-cross-v5
+ - name: Install mpy-cross v5
+ run: |
+ pip install mpy-cross-v5
+
+ - name: Pre-compile module using mpy-cross v5
+ run: |
+ mkdir -p precompiled/v5/max30102
+ python -m mpy_cross_v5 max30102/max30102/__init__.py -o precompiled/v5/max30102/__init__.mpy
+ python -m mpy_cross_v5 max30102/max30102/circular_buffer.py -o precompiled/v5/max30102/circular_buffer.mpy
+ ls -l precompiled/v5/max30102
+
+ - name: Upload artifact for MicroPython version <=1.18
+ uses: actions/upload-artifact@v2
+ with:
+ name: v1.18_precompiled_module
+ path: precompiled/v5
+
+ precompile-v6:
+ runs-on: ubuntu-latest
+
+ steps:
+ - uses: actions/checkout@v3
+ with:
+ path: max30102
+
+ - uses: actions/checkout@v3
+ with:
+ repository: 'micropython/micropython'
+ path: micropython
+
+ - name: Set up Python
+ uses: actions/setup-python@v3
+ with:
+ python-version: '3.8'
+
+ # For MicroPython version 1.19+, compile with mpy-cross-v6
+ - name: Install mpy-cross v6
+ run: |
+ pip install mpy-cross-v6
+
+ - name: Pre-compile module using mpy-cross v6
+ run: |
+ mkdir -p precompiled/v6/max30102
+ python -m mpy_cross_v6 max30102/max30102/__init__.py -o precompiled/v6/max30102/__init__.mpy
+ python -m mpy_cross_v6 max30102/max30102/circular_buffer.py -o precompiled/v6/max30102/circular_buffer.mpy
+ ls -l precompiled/v6/max30102
+
+ - name: Upload artifact for MicroPython version >=1.19
+ uses: actions/upload-artifact@v2
+ with:
+ name: v1.19_precompiled_module
+ path: precompiled/v6

.github/workflows/python-publish.yml

@@ -1,37 +1,35 @@
-# This workflow will upload a Python Package using Twine when a release is created
+# This workflow will upload a Python Package to PyPi using Twine when a release is created
 # For more information see: https://help.github.com/en/actions/language-and-framework-guides/using-python-with-github-actions#publishing-to-package-registries
 
-# This workflow uses actions that are not certified by GitHub.
-# They are provided by a third-party and are governed by
-# separate terms of service, privacy policy, and support
-# documentation.
-
 name: Upload Python Package
 
 on:
  release:
- types: [published]
+ types: [ published ]
 
 jobs:
- deploy:
-
+ publish:
  runs-on: ubuntu-latest
 
  steps:
- - uses: actions/checkout@v2
- - name: Set up Python
- uses: actions/setup-python@v2
- with:
- python-version: '3.x'
- - name: Install dependencies
- run: |
- python -m pip install --upgrade pip
- pip install build
- pip install twine
- - name: Build package
- run: python -m build -s
- - name: Publish package
- uses: pypa/gh-action-pypi-publish@27b31702a0e7fc50959f5ad993c78deac1bdfc29
- with:
- user: __token__
- password: ${{secrets.PYPI_API_TOKEN}}
+ - uses: actions/checkout@v2
+
+ - name: Set up Python
+ uses: actions/setup-python@v2
+ with:
+ python-version: '3.x'
+
+ - name: Install dependencies
+ run: |
+ python -m pip install --upgrade pip
+ pip install build
+ pip install twine
+
+ - name: Build package
+ run: python -m build -s
+
+ - name: Publish package
+ uses: pypa/gh-action-pypi-publish@27b31702a0e7fc50959f5ad993c78deac1bdfc29
+ with:
+ user: __token__
+ password: ${{secrets.PYPI_API_TOKEN}}

README.md

@@ -11,25 +11,30 @@ feedback in the Discussions section.
 
 ## Table of contents
 
-* [Disclaimer](#disclaimer)
-* [Usage](#usage)
- + [1 - Including this library into your project](#1---including-this-library-into-your-project)
- - [1a - **network-enabled MicroPython ports**](#1a---network-enabled-micropython-ports)
- - [1b - **manual way** (no Internet access required)](#1b---manual-way-no-internet-access-required)
- + [2 - I2C setup and sensor configuration](#2---i2c-setup-and-sensor-configuration)
- - [I2C connection](#i2c-connection)
- - [Sensor setup](#sensor-setup)
- + [3 - Data acquisition](#3---data-acquisition)
- - [Read data from sensor](#read-data-from-sensor)
- - [Notes on data acquisition rate](#notes-on-data-acquisition-rate)
- - [Die temperature reading](#die-temperature-reading)
-* [Changelog](#changelog)
-* [Acknowledgements](#acknowledgements)
-* [Tested platforms and known issues](#tested-platforms-and-known-issues)
-* [Other useful things](#other-useful-things)
- + [Realtime plot over Serial](#realtime-plot-over-serial)
- + [Sensor clones](#sensor-clones)
- + [Heartrate and SPO2 estimation](#heartrate-and-spo2-estimation)
+# Table of contents
+
+- [Maxim MAX30102 MicroPython driver](#maxim-max30102-micropython-driver)
+ - [Table of contents](#table-of-contents)
+ - [Disclaimer](#disclaimer)
+ - [Usage](#usage)
+ - [1 - Including this library into your project](#1---including-this-library-into-your-project)
+ - [1a - **network-enabled MicroPython ports**](#1a---network-enabled-micropython-ports)
+ - [1b - **manual way** (no Internet access required)](#1b---manual-way-no-internet-access-required)
+ - [2 - I2C setup and sensor configuration](#2---i2c-setup-and-sensor-configuration)
+ - [I2C connection](#i2c-connection)
+ - [Sensor setup](#sensor-setup)
+ - [3 - Data acquisition](#3---data-acquisition)
+ - [Read data from sensor](#read-data-from-sensor)
+ - [Notes on data acquisition rate](#notes-on-data-acquisition-rate)
+ - [Die temperature reading](#die-temperature-reading)
+ - [Changelog](#changelog)
+ - [Acknowledgements](#acknowledgements)
+ - [Tested platforms](#tested-platforms)
+ - [Other useful things and troubleshooting](#other-useful-things-and-troubleshooting)
+ - [Realtime plot over Serial](#realtime-plot-over-serial)
+ - [Sensor clones](#sensor-clones)
+ - [Heartrate and SPO2 estimation](#heartrate-and-spo2-estimation)
+ - [ESP8266 module import error](#esp8266-module-import-error)
 
 ## Disclaimer
 
@@ -46,17 +51,22 @@ A full example is provided in `/example` directory.
 
 #### 1a - **network-enabled MicroPython ports**
 
-> Warning: in latest MicroPython releases `upip` has been deprecated in favor of [`mip`](https://docs.micropython.org/en/latest/reference/packages.html#package-management). This module is compatible with both of them. Please use the package manager included into your MicroPython version.
+> Warning: in latest MicroPython releases `upip` has been deprecated in favor
+> of [`mip`](https://docs.micropython.org/en/latest/reference/packages.html#package-management). This module is
+> compatible
+> with both of them. Please use the package manager included into your MicroPython version.
 
-If your MicroPython version supports `mip` package manager, put these lines **after** the setup of an Internet connection:
+If your MicroPython version supports `mip` package manager, put these lines **after** the setup of an Internet
+connection:
 
 ```python
 import mip
 
 mip.install("github:n-elia/MAX30102-MicroPython-driver")
 ```
 
-If your MicroPython version supports `upip` package manager, put these lines **after** the setup of an Internet connection:
+If your MicroPython version supports `upip` package manager, put these lines **after** the setup of an Internet
+connection:
 
 ```python
 import upip
@@ -280,8 +290,8 @@ resolution of 0.0625°C, but be aware that the accuracy is ±1°C.
 ## Changelog
 
 - v0.4.1
- - Changed the module files organization.
- - Added support to `mip` package manager.
+  - Changed the module files organization.
+  - Added support to `mip` package manager.
 - v0.4.0
  - According to some best practices discussed [here](https://forum.micropython.org/viewtopic.php?f=2&t=12508), some
  changes have been made.
@@ -324,24 +334,26 @@ This work is a lot based on:
 
  A port of the library to MicroPython by **kandizzy**
 
-## Tested platforms and known issues
+## Tested platforms
 
-The library has been tested on _TinyPico_ (board based on _ESP32-D4_) running 'tinypico-20210418-v1.15.bin' MicroPython
-firmware, connected to a genuine Maxim 30102 breakout
-board ([MAXREFDES117#](https://www.maximintegrated.com/en/design/reference-design-center/system-board/6300.html)).
+- _TinyPico_ (board based on _ESP32-D4_) running 'tinypico-20210418-v1.15.bin' MicroPython firmware, connected to a
+  genuine Maxim 30102 breakout
+ board ([MAXREFDES117#](https://www.maximintegrated.com/en/design/reference-design-center/system-board/6300.html)).
 
-Tested ([thanks to ebolisa](https://github.com/n-elia/MAX30102-MicroPython-driver/issues/4)) and working on _Raspberry Pi
-Pico_ + non-Maxim breakout board.
+- _Raspberry Pi
+ Pico_ + non-Maxim breakout board ([thanks to ebolisa](https://github.com/n-elia/MAX30102-MicroPython-driver/issues/4))
 
-Tested and working on _ESP32-S3_ (_Unexpected Maker TinyS3_) + non-Maxim breakout board.
+- _ESP32-S3_ (_Unexpected Maker TinyS3_) running MicroPython v1.18 stable and MicroPython v1.19 stable + non-Maxim
+ breakout board.
 
 **I2C read issue**: as discussed in the [MicroPython forum](https://forum.micropython.org/viewtopic.php?f=2&t=12508) and
 in the
-[GitHub Discussions section](https://github.com/n-elia/MAX30102-MicroPython-driver/discussions/5#discussioncomment-2899588),
+[GitHub Discussions section](https://github.com/n-elia/MAX30102-MicroPython-driver/discussions/5#discussioncomment-2899588)
+,
 some board/sensor combinations lead to an issue that makes the first I2C read fail. This issue can be mitigated by
 running an I2C scan before actually using the sensor, as shown in the provided example.
 
-## Other useful things
+## Other useful things and troubleshooting
 
 ### Realtime plot over Serial
 
@@ -366,3 +378,24 @@ your phone camera to check), then you have to collect IR samples as red ones and
 If you're looking for algorithms for extracting heartrate and SPO2 from your RAW data, take a
 look [here](https://github.com/aromring/MAX30102_by_RF)
 and [here](https://github.com/kandizzy/esp32-micropython/tree/master/PPG)
+
+
+### ESP8266 module import error
+
+If you get an error like this:
+
+```
+MemoryError: memory allocation failed,allocating 416 bytes
+```
+
+then your heap is too small to allocate the module. You can try to pre-compile the module using `mpy-cross` and then
+import it as usual. You can either use the precompiled module provided in
+the [GitHub Action artifacts](https://github.com/n-elia/MAX30102-MicroPython-driver/actions/workflows/pre-compile.yml)
+or compile it
+yourself.
+
+In the first case, you just have to replace the `max30102` folder of the module with the one provided in the artifact
+archive.
+
+In either case, you have to choose the proper version of `mpy-cross` according to your Micropython version: for
+MicroPython v.1.18 and below, you can use `mpy-cross-v5`, while for MicroPython v1.19 you have to use `mpy-cross-v6`.