MagTag Data Logger is a CircuitPython data logger that permits ambient temperature monitoring in the environment of the device using an internal sensor on the MagTags PCB (other data could readily be logged). With minimal calibration, obviates the need for additional external hardware. Typically 1 C resolution, ±1 C accuracy, ~0.35 C / minute for a 5 C step change, range -20 to +60 C. Based on Adafruit example code, additional features include Segment numeric indicator and Data graphing on the e-ink display of the Adafruit Magtag device.
The CircuitPython implementation of the MagTag Data Logger is intended to allow ambient e.g. room temperature monitoring without need for additional sensing hardware. The software permits logging and on board graphing of the measured temperature. For accurate measurements a reference temperature point should be established, perhaps with reference to an existing room sensor (see Calibration section) and this operation should only be required once. Where relative temperatures are satisfactory, no calibration is necessary. Other data from a variety of sources could be logged with relatively minor modification. General information on CircuitPython data loggers can be found here.
Requirements
Optional
Download and unzip the Repository Zip file.
Make sure you are using the correct version of CircuitPython for the release.
Then copy the files located in the 'dist' folder of the unzipped files to the CIRCUITPY drive (root) folder of the Adafruit MagTag.
There are two setup files:
| File | Comment |
|---|---|
| secrets.py | WiFi and other account specific settings |
| settings.toml | Unit specific settings i.e. Calibration, identifiers, options |
Use of settings.toml is covered below and the comments in the file, details on secrets.py are in the link here.
WiFi or other settings in secrets.py are not required to use the logger, some features can not be used without WiFi access.
Note
- The implementation may optionally use WiFi and thus a secrets.py file should typically have any entries, it must be in the CIRCUITPY drive .
- Following release of CircuitPython 7 to stable, the code implements switch off of HID disk and serial ports via boot.py.
- If electing to use alternate CircuitPython releases e.g. CircuitPython 7.1.x etc. you need to replace the lib .mpy files with the release counterparts in the lib folder.
- The 'Magtag PowerPoint Layout 03.pptx' file is a Microsoft™ PowerPoint™ pack with slidemaster backgrounds consisting of a Magtag graphic to enable graphic design prior to coding. The image scale approximates to 2:1 The file should load into Google™ Docs, though this has not be tested.
- Ensure any temperature changes result in no condensation in or on the electronics
- LiPo cells may degrade at temperature extremes
- Display may not operate at low temperatures, the software is coded to omit updates below -9 C
- Operation outside the manufacturers specification(s) for any component must not occur
Optional - A LiPo battery, supported by the MagTag.
Suggested - Acrylic + Hardware Kit for Adafruit MagTag
Design of the MagTag means that when the unit is powered from the USB port the on board voltage regulator and ESP32-S2 cause the units PCB to be heated. To approximately 32 C with a room ambient of 22 C under typical continuous use conditions with Mu editor (even with sleep modes). This heating effect (see image below) causes a measurement error and unless the PCB temperature is desired, powering from the USB port typically prevents ambient temperature sensing due to the typical heat soak from the ESP32-S2 and voltage regulators and particularly so when charging a battery as is shown in the thermal image here.
Without a battery, Mu editor and USB services together with arranging a power on duration to be suitably short and a power off duration to be suffciently long. Permit the unit to maintain its self at an ambient temperature. Thus allowing an arrangment for a permenantly powered temperature monitor. Alternatively power can be drawn from a LiPo battery (keeping in mind whilst being charged via the MagTag the PCB warms as shown). It should be noted that when the LiPo has charged the unit does cool. However, the cycle for recharging the LiPo is not controllable by software and may confuse interpretation of readings as a result.
Use of magnetic stand off feet to attach the MagTag to a metallic surface will modify the devices temperature responsiveness and thermal heat soak profile. Where not powered from the USB port and the attachment point moves largely with the environment (room) the impact would be anticipated to somewhat limited, if somewhat slower than the air temperature change.
For sensing of the ambient temperature, air flow over the rear of the MagTag should ideally not be restricted. Testing within a plastic case where the MagTag was substantially attached to the housing demonstrated reasonable thermal responsiveness arising from the design decisions, materials and construction.
To calibrate the device a performance curve was obtained as shown below. Depending on the level of accuracy required various mechanisms might be employed for calibration, such as multi degree (order) polynomials or lookup tables. In the release software it was elected to implement a straightforward compensation based on a straight line y = mx + c. The LIS3DH MEMS digital output motion sensor device specification points to 1 C per bit. Each measurement point of the performane curve was repeated three times. The variation observed might be associated with measurement uncertainty of the characterisation system rather than the device its self. For other MagTag devices it is probably satisfactory to assess the offset at a reference temperature to achieve reasonable performance.
From two randomly selected MagTag devices purchased at the same time, the offset difference was found to be ~6 units.
Calibration is performed by adjusting values in the settings.toml file stored in the root folder of the CIRCUITPY MagTag device.
The values m0 and c0 are set to 1.0 and 0.0 respectively in the settings.toml distribution. To cause the display to scale to raw sensor units used in the compensation calculation y = mx + c . Where m is assigned from m0 and c is assigned from c0 via the settings.toml file (default values are applied if no settings exist).
For basic adjustment, if assuming similar performance to the curve shown:
- Set the value of m0 to 0.9826 from the default of 1.0 in the settings.toml file
- Using a charged battery and no USB connection, with the default display sample period of 120 seconds
- Allow the unit to thermally settle at a fixed reference temperature for one hour
(The display should update every 2 minutes, a WiFi connection is not required) - Edit the value c0 in the settings.toml to offset the reading to the stabilised reference temperature
(e.g if the displayed value is 20 C too low, set c0 to 20.0 in the settings.toml file and reboot the device)
A more rigorous approach might be to arrange to identify the raw 0 temperature or even perform a custom multi point calibration.
To perform a custom calibration, set m0 to 1.0 and c0 = 0.0 in the settings.toml file to cause data display in raw values. These can then be read to create a calibration curve similar to that shown for specific temperature(s). A number of approaches can be taken such as multipoint calibration as desired. In the case of the characteristic shown the reference temperature indication had a resolution of 10 times the nominal raw value increments. Care was exercised to maintain as low a temperature gradient across the device as practicable e.g. in a thermally controlled environment.
Note The settings.toml file can be accessed by keeping the button D11 next to the USB connector depressed during the boot sequence. The boot sequence is initiated by pressing the reset button once. This will cause the boot.py file to detect the button press and enable the USB drivers required for serial port REPL and emulated USB memory device etc.
The curve below is taken from a unit logging at 120 second intervals from a fully charged 2000 mAh PKCELL LP803860 LiPo battery. The WiFi signal strength was ~-30 dBm, the WiFi Channel has been identified and a maximum 10 seconds permitted for WiFi acquisition in the settings.py file.
It should be noted that placing the LiPo battery attached to the rear of the MagTag will affect the thermal inertia. The capacity of the LiPo battery impacts the charge time. LiPo battery warnings are set to 3.7 Volts, ~88% new battery terminal voltage, lower voltages are not recomended. It was found allowing battery terminal voltage to fall lower also resulted in excessive charge times.
The data below was sampled every 120 seconds over a number of days.
The raw data is shown with a test data filter (in Orange). The (optional) filter configuration is selected to introduce minimal delay, exhibit good step response to (relatively) rapidly changing temperature data, have straight forward implementation and a response that is a good match for the experienced environment. The test filter has the transfer function y[n] = (0.1 * x[n]) + (0.9 * x[n-1]), these are (will be) settable in the settings.toml file such that the performance can be readily adjusted.
The graphed data for Battery and Temperature were retreived from the published MQQT data streams (see MQQT below).
Two MQQT streams are published if suitable settings are applied to the 'secrets.py' file. The streams are Temperature and Voltage of the battery (or USB if powered from a USB port).
The data taken over a number of days shows that if the 2000 mAh battery terminal voltage drop due to dicharge is kept to less than ~ 0.1 Volt, ~ 8 hours. The subsequent re-charge cycle does not unduly influence measured temperature. Voltage delta might be used to detect removal of the USB power as the MagTag can not identify the power source.
See here for more information on MQQT.
The key features are shown below:
An external temperature (or other) sensor(s) channel could readily be substituted, via the MagTags QWIC StemmaQT data connections if desired.
DSEG14 Font credit https://github.com/keshikan/DSEG Release 7
All information is For Indication only.
No association, affiliation, recommendation, suitability, fitness for purpose should be assumed or is implied.
Registered trademarks are owned by their respective registrants.