Awesome

MicroPython (and CircuitPython) driver module for MLX90615 infrared temperature sensor

MicroPython and CircuitPython drivers for MLX90615 infrared temperature sensor, with features :

• reading all the RAM registers, i. e., ambient/object temperature and raw IR data;
• reading and setting of all configurations in EEPROM;
• checking the PEC (Packet Error Code, based on CRC-8) for each reading, as default;
• use of I2C (SMBus);
• enable/disable and configuration of PWM mode;
• sleep and wake functions;
• optional simplified versions with low memory usage.

These drivers for MLX90615 are optimised for low memory usage :

• by using and returning integer values as possible, as float values would allocate more RAM;
• documentation is outside the code;
• the 'no-errors' version has no error checking for reading the sensor, nor error messages;
• the 'simple' version has just the most important functions.

1) MLX90615

The Melexis MLX90615 infrared thermometer :

• is a miniature infrared thermometer for non-contact temperature measurements;
• has small size and good accuracy, so it is especially suited for medical applications like ear or forehead thermometers;
• has I2C (SMBus) and PWM communication options;
• features PEC (Packet Error Code, based on CRC-8) for each data/EEPROM reading;
• usually consumes 1.5 mA in active mode using I2C, or 3 uA in low power/sleep mode;
• comes factory calibrated in wide temperature range, -20 to 85°C for ambient/sensor temperature and -40 to 115°C for object temperature, with a resolution of 0.02 °C;
• has factory calibrated accuracy of ±0.2°C for object temperature range 36-39°C and ±0.3°C for object temperature range 32-42°C, when ambient/sensor temperature is between 16-40°C;
• updates the temperature and raw IR data in RAM at a 2 Hz rate (0.5 s period);
• recommended object distance is <= 3 cm, like 2 cm, but not touching the sensor.

Boards with MLX90615 :

• SeeedStudio Grove MLX90615 Digital Infrared Temperature Sensor - US$9.00;

  <img src="https://files.seeedstudio.com/wiki/Grove-Digital_Infrared_Temperature_Sensor/img/Grove%EF%BC%8DDigital_Infrared_Temperature_Sensor_2.jpg" alt="SeeedStudio Grove MLX90615 Digital Infrared Temperature Sensor" width="400"/>

• GY-90615 Digital Infrared Temperature Sensor Module MLX90615 - Alibaba.com - US$7.80.

  <img src="https://sc01.alicdn.com/kf/Hbc672028c02041b48e41a7a8983e9ba6m.jpg" alt="GY-90615" width="250"/>

2) MicroPython/CircuitPython driver definitions

The 'no-errors' version of the driver doesn't check the PEC (Packet Error Code, based on CRC-8) on each reading, doesn't read the value after writing to EEPROM to confirm, nor have specific error messages. Advantages : lower RAM usage, faster to import and a little bit to run the functions. Disadvantages : less robust, more difficult to debug errors.

The 'simple' version of the driver has just the most important functions : read ambient and object temperatures, read unique ID, read EEPROM and read of any register. Advantages : robust, lower RAM usage. Disadvantages : not possible to change MLX90615 configuration, less features.

The 'simple' and 'no-errors' version combined the above limitations.

The BBC Micro:bit full version is limited to fewer functions due to RAM limitations, so there are no sleep/wake, PWM and IIR filter functions.

The full version of the driver is described in the table below.

All the functions can return error messagens using exceptions, so it is recommended to call them inside Micro(Python) try/except.

When the function has the argument option :

• 'pec_check' (packet error code check), it is enabled by default and it checks the reading with a CRC-8, with error message for reading error;
• 'eeprom_read_check', if True it reads the value after writing to EEPROM to confirm;
• 'eeprom_write_time', it defines the erase/write time in ms before and after EEPROM operations, the recommended and default value is 50 ms.

( * ) : writing to I2C address in EEPROM is risky because sometimes (3-10%) there is an error while erasing/writing to the EEPROM, rendering the I2C connection to MLX90615 unstable.

3) Examples

3.1) Initialization

Beware that MLX90615 I2C bus frequency should be in the range of 10-100 kHz (see the section '8.4.7 Timing specification' of the MLX90615 datasheet). I2C frequencies lower than 100 kHz are usually needed for longer cables connecting the microcontroller to the MLX90615 sensor.

If MLX90615 sensor is on a break-out board, it usually has pull-up resistors for I2C SDA and SCL pins. But the microcontroller internal pull-up or even external resistors may be needed depending on the lenght of cable connecting to the MLX90615, electromagnetic interference from the environment, etc.

3.1.1) Pyboard (Lite) v1.x

import machine
import mlx90615
i2c = machine.I2C(scl='X9', sda='X10', freq=100000)   # Software I2C
i2c.scan()   # returns : [91]  
irsensor = mlx90615.MLX90615(i2c)

3.1.2) Pyboard D and link above

import machine
import mlx90615
machine.Pin('EN_3V3').on()
machine.Pin('PULL_SCL', machine.Pin.OUT, value=1)     # 5.6k pull-up, if needed
machine.Pin('PULL_SDA', machine.Pin.OUT, value=1)     # 5.6k pull-up, if needed
i2c = machine.I2C(scl='X9', sda='X10', freq=100000)   # Software I2C
i2c.scan()   # Output : [91]
irsensor = mlx90615.MLX90615(i2c)

3.1.3) ESP8266

import machine
import mlx90615
i2c = machine.I2C(sda=machine.Pin(4), scl=machine.Pin(5), freq=100000)   # Software I2C
i2c.scan()   # Output : [91]
irsensor = mlx90615.MLX90615(i2c)

3.1.4) ESP32

import machine
import mlx90615
i2c = machine.I2C(sda=machine.Pin(21), scl=machine.Pin(22), freq=100000)   # Software I2C
i2c.scan()   # Output : [91]
irsensor = mlx90615.MLX90615(i2c)

3.1.5) BBC Micro:bit

from microbit import i2c
import mlx90615
i2c.scan()   # Output : [91]
irsensor = mlx90615.MLX90615(i2c)

3.1.6) Pycom boards like LoPy4

import machine
import mlx90615
i2c = machine.I2C(2, baudrate=100000)   # Software I2C
i2c.scan()   # Output : [91]
irsensor = mlx90615.MLX90615(i2c)

3.2) Reading the MLX90615 IR temperature

irsensor.read_raw_ir_data()    # Output : 108       # IR raw data with no physical unit
irsensor.read_ambient_temp()   # Output : 3059      # i.e., 30.59 C
irsensor.read_object_temp()    # Output : 3621      # i.e., 36.21 C

3.3) Reading the MLX90615 configuration

It is recommended that the ID and EEPROM data of each MLX90615 unit be saved (in a file like spreadsheet, etc) as a backup. Because the EEPROM includes the factory calibration data which is different for earch sensor unit, the EEPROM registers can be written by mistake, the EEPROM can become corrupted, etc.

irsensor.read_id()            # Output : 7623496   # 32 bits unique ID
irsensor.read_eeprom()        # Output : [13659, 2499, 5321, 15892, 24768, 13658, 17180, 8209, 73, 32786, 7504, 616, 6765, 14908, 21320, 116]

Factory default values are emissivity = 1.00 and I2C address = 0x5B (91 in decimal) :

irsensor.read_emissivity()    # Output : 100       # e = 1.00
irsensor.read_i2c_address()   # Output : 91 

3.4) Setting the MLX90615 configuration

Emissivity depends on the material type, so it should be set to correctly measure the object temperature :

irsensor.set_emissivity(97)   # e = 0.97

The current I2C address of MLX90615 should be 0x00 to avoid errors while setting the new I2C address in EEPROM :

irsensor = mlx90615.MLX90615(i2c, address=0x00)
irsensor.set_i2c_address(0x5C)
irsensor.read_i2c_address()      # Output : 92        # 92 = 0x5C, checked

4) Benchmarks

When not stated, using MicroPython v1.12 firmware, with single float precision, default clock speed for the board, driver on internal flash memory and wireless disabled.

OOM = Out Of Memory (error), so the driver version can not fit in the available RAM.

Table for driver 'mlx90615.py' v0.2.1 with all features. '[simple]' means driver 'mlx90615_simple.py'/'mlx90615_microbit_simple.py' v0.2.1 with simple read functions :

Table for driver 'mlx90615_no-errors.py'/'mlx90615_microbit_no-errors.py' v0.2.1 without error checking. '[simple]' means driver 'mlx90615_simple_no-errors.py'/'mlx90615_microbit_simple_no-errors.py' v0.2.1 with simple read functions and without error checking :

Pyboard Lite v1.0, default clock @ 96 MHz.
Pyboard v1.1, default clock @ 168 MHz.
Pyboard D SF2W, default clock @ 120 MHz.
Pyboard D SF6W, firmware with double precision, default clock @ 144 MHz.
ESP8266 in Wemos D1 Mini, default clock @ 80 MHz.
BBC Micro:bit, with MicroPython v1.9.2-34-gd64154c73, micro:bit v1.0.1, default clock @ 16 MHz.
ESP32 in M5Stack Core Basic, default clock @ 160 MHz.
ESP32 PSRAM in M5Stack Core Gray PSRAM, default clock @ 160 MHz.
LoPy v1 has a ESP32 without PSRAM, LoPy4 with PSRAM, both with Pycom MicroPython 1.20.2.rc7, default clock @ 160 MHz.

5) References

MLX90615 documentation :

1. official Melexis MLX90615 web page, with datasheet, application notes, etc;
2. Melexis Comparative Table of InfraRed Thermometer Family - MLX90614 and MLX90615;
3. Comparative table between the MLX90614 and the MLX90615.

MLX90615 tutorials :

• Grove - MLX90615 Digital Infrared Temperature Sensor - SeedStudio Wiki, for Arduino;
• MLX90615 infrared thermometer and Arduino - Arduino Learning.

Other MLX90615 drivers :

1. 'Arduino library for MLX90615 module from Seeed-Studio' has some features like optional SoftI2cMaster library, PEC/CRC-8 checking and writing to EEPROM registers;
2. 'mlx90615-on-raspberryPi from paulvha' is a C driver and interactive software for Raspberry Pi, with many features and excelent documentation complementing the official MLX96015 documentation, like citation of the time delay needed after erasing/writing to the MLX90615 EEPROM;
3. 'A minimal Arduino library for Melexis MLX90615' from skiselev has only some reading functions;
4. MLX90615 library functions from Melexis is a reference C++ driver with many features and good documentation.