MEMS Accelerometer Free Fall Detection

Micro Electro Mechanical Systems (MEMS) accelerometers have been available since the 1990’s. MEMS creates a microscopic mechanical sensing structures that is coupled with microelectronic circuits to measure physical parameters such as acceleration. One of the first applications of the silicon based MEMS accelerometer was to protect hard drives (HDD) media when being dropped while rotating. When free fall was detected the HDD head would be moved to a safe zone to protect the media.

When a MEMS accelerometer is in free fall all acceleration values move towards zero. The figures below help to understand why this is true (Figures from Physical StackExchange). When in free fall the frame and mass are both affected by the same acceleration so the force acting on the spring nears zero. For a MEMS accelerometer the measured acceleration nears zero.

An inexpensive MEMS accelerometer is the LIS3DH. This unit is a 3-axis accelerometer with scalable ranges (±2g/±4g/±8g/±16g), supports multiple data rates, is low power, has three 10-bit ADCs, and interfaces over I2C or SPI. This accelerometer can also generate interrupts for tap, double-tap, orientation changes, and freefall detection. These accelerometers are available on breakout boards from multiple vendor such as Adafruit and Sparkfun.

To configure the LIS3DH for free fall detection a threshold level in g’s and duration are programmed in device registers. The design tip DT0100 shows an example of setting the level to ~350mg with a duration of 30ms. For the interrupt to occur a level of 350mg or less must be detected on all three axis accelerometers for a minimum of 30ms before the interrupt occurs as shown in the figure below from the ST design note.

For this example I used an Adafruit LIS3DH breakout board. Adafruit does a nice job of providing libraries for their products. The Adafruit LIS3DH library unfortunately does not provide a free fall interrupt method. Normally I would inherit the library object and create my own methods but the library made key communication variables private, so this wasn’t an option without modifying the library. My client’s application did not required any other processing so I created code to replicate the free fall interrupt function in the Arduino loop().

The code uses the Adafruit sensors_event_t type, which returns the accelerometer values in m/s2. To match the design tip the free fall threshold would be set to 3.432 m/s2 (1g = 9.08665 m/s2). With a free fall threshold of 350mg, I found it too easy to enter free fall so I reduced the value to about 50mg, which worked well. When all three axis meet the free fall detection threshold, the free fall duration is checked. If the amount of time exceeds the free fall duration then a LED is turned on (the client turned a servo motor) indicating the unit is in free fall. If the free fall threshold isn’t met, then the duration time is updated to the current time using millis().

Below is the sample code emulating the LIS3DH free fall detection.

// Free Fall Detection
// Adafruit LIS3DH Accelerometer with SPI
// Adapted from Adafruit library acceldemo.ino

#include <SPI.h>
#include <Adafruit_LIS3DH.h>
#include <Adafruit_Sensor.h>

// Hardware Pins
#define LIS3DH_CS 10  // SPI device select
#define LED_PIN   4   // LED output pin to indicate freefall active high

// Operating Parameters
#define FREEFALL_ACCEL_THRESHOLD  0.5 // freefall threshold in m/s^2, 1g = 9.80665 m/s^2
#define FREEFALL_TIME_THRESHOLD   30  // freefall time threshold in ms

// hardware SPI for accelerometer
Adafruit_LIS3DH lis = Adafruit_LIS3DH(LIS3DH_CS); // accel object
sensors_event_t event;                            // sensor data to evaluate for freefall

// timer for free fall
uint32_t freeFallTime;           // timer for consecutive freefall detections

void setup(void) {
  Serial.begin(115200);
  while (!Serial) delay(10);     // will pause Zero, Leonardo, etc until serial console opens

  // setup output control pin for LED
  pinMode(LED_PIN, OUTPUT);
  digitalWrite(LED_PIN, LOW);
  
  if (! lis.begin()) {
    Serial.println("Couldnt start");
    while (1) yield();
  }

  lis.setRange(LIS3DH_RANGE_2_G);           // set to 2G range
  lis.setDataRate(LIS3DH_DATARATE_400_HZ);  // sample at fastest rate (2.5ms)

  Serial.println("Free Fall Detection with LIS3DH");

  freeFallTime = millis();
}

void loop() {

  lis.getEvent(&event);   // get latest data

  // detect free fall
  if(abs(event.acceleration.x) <= FREEFALL_ACCEL_THRESHOLD &&
     abs(event.acceleration.y) <= FREEFALL_ACCEL_THRESHOLD &&
     abs(event.acceleration.z) <= FREEFALL_ACCEL_THRESHOLD) {

    if((millis() - freeFallTime) >= FREEFALL_TIME_THRESHOLD) {
      digitalWrite(LED_PIN, HIGH);
    }
  }
  else { // not in freefall reset timer
    freeFallTime = millis();
  }
}

ESP32 deep Sleep (RTC) GPIO Output

In the course of developing an ESP32 battery based application I was stumped along with others, on how to maintain a GPIO output in a known state while in deep sleep. My plan was to hold an external peripheral in a reset state to minimize it’s power. The reset signal was an active low signal and the external peripheral had a 10K pullup resistor on the signal. I program the ESP32 in the Arduino environment so I had to find a solution that supported this IDE. I performed a bunch of searches and finally found a working example by Xabi Alaez.

The ESP32 has several “sleep” modes that are listed below. A great article about ESP32 sleep modes is found on the Last Minute Engineers web page.

  • Active keeps everything running including WiFi, Bluetooth, and processing core at all times. This mode consumes more than 240mA with some power spikes as high as 790mA.
  • Modem Sleep is Active minus the WiFi, Bluetooth, and radio. Dependent on the clock speed, which is programmable, consumes between 3mA (low clock speed) to 20mA (high clock speed).
  • Light Sleep the CPU(s) clock is gated while the RTC and ULP co-processor are active. This sleep mode has full RAM retention. Once entering Light Sleep a wake-up source is needed to resume processing. This power consumption is less than 1mA.
  • Deep Sleep the CPU(s), most RAM, and all digital peripherals are powered off while the ULP co-processor and RTC components remain operational. The power consumption is about 0.15mA with the ULP co-processor running.
  • Hibernation only has one RTC timer running and a few RTC GPIOs needed to wake up the chip from hibernation mode. Power consumption is about 2.5uA.

I was most interested in Deep Sleep and Hibernation modes. It turns out you control the power domains before entering Deep Sleep to create Hibernation mode (no API call for hibernation sleep). This also means you can be selective in which power domains are enabled to create a “custom” sleep mode that has less current consumption than Deep Sleep, but not as good as Hibernation.

The ESP power domains are controlled by calling esp_deep_sleep_pd_config() with the power domain and options that include ESP_PD_OPTION_OFF, ESP_PD_OPTION_ON, and ESP_PD_OPTION_AUTO. The auto option powers down the power domain unless it is needed by one of the wakeup options. The different ESP power domains are:

  • ESP_PD_DOMAIN_RTC_PERIPH for RTC IO, sensors and ULP co-processor.
  • ESP_PD_DOMAIN_RTC_SLOW_MEM for RTC slow memory.
  • ESP_PD_DOMAIN_RTC_FAST_MEM for RTC fast memory.
  • ESP_PD_DOMAIN_XTAL for XTAL oscillator.
  • ESP_PD_DOMAIN_RTC8M for internal 8M oscillator.
  • ESP_PD_DOMAIN_VDDSDIO for VDD_SDIO.

During Deep Sleep the only GPIO pins that are available are the RTC IO (RTC_GPIO), which are part of the ESP_PD_DOMAIN_RTC_PERIPH power domain. The ULP co-processor is also active in this power domain. The table below shows the mapping of GPIO pins to analog and RTC functions available through the RTC Mux. The table information is from the Espressif Systems ESP32 Technical Reference Manual Version 4.2, section 5.11, table 21.

GPIO NumRTC GPIO NumAnalog
1
Analog
2
Analog
3
RTC
1
RTC
2
360ADC_HADC1_CH0RTC_GPIO0
371ADC_HADC1_CH1RTC_GPIO1
382ADC_HADC1_CH2RTC_GPIO2
393ADC_HADC1_CH3RTC_GPIO3
344ADC1_CH6RTC_GPIO4I2C_SCL
355ADC1_CH7RTC_GPIO5I2C_SDA
256DAC_1ADC2_CH8RTC_GPIO6I2C_SCL
267DAC_2ADC2_CH9RTC_GPIO7I2C_SDA
338XTAL_32K_NADC1_CH5TOUCH8RTC_GPIO8
329XTAL_32K_PADC1_CH4TOUCH9RTC_GPIO9
410ADC2_CH0TOUCH0RTC_GPIO10
011ADC2_CH1TOUCH1RTC_GPIO11
212ADC2_CH2TOUCH2RTC_GPIO12
1513ADC2_CH3TOUCH3RTC_GPIO13
1314ADC2_CH4TOUCH4RTC_GPIO14
1215ADC2_CH5TOUCH5RTC_GPIO15
1416ADC2_CH6TOUCH6RTC_GPIO16
2717ADC2_CH7TOUCH7RTC_GPIO17
GPIO Pin Function via RTC Mux Selection

To setup the RTC Mux and control the RTC GPIOs in the Arduino environment, calls are made to rtc_gpio_* functions. These functions allow you to initialize the pin as RTC GPIO and set it’s direction and level. My test code adapted from Xabi Alaez’s is shown below.

#include "driver/rtc_io.h"
gpio_num_t RST_PIN = GPIO_NUM_14;

void setup() {
  rtc_gpio_init(RST_PIN);
  rtc_gpio_set_direction(RST_PIN,RTC_GPIO_MODE_OUTPUT_ONLY);
  // toggle reset pin
  rtc_gpio_set_level(RST_PIN,1); //GPIO high
  rtc_gpio_set_level(RST_PIN,0); //GPIO LOW
  rtc_gpio_set_level(RST_PIN,1); //GPIO high
  delay(5000);  // wait
  rtc_gpio_set_level(RST_PIN,0); //GPIO hold low
  esp_sleep_pd_config(ESP_PD_DOMAIN_RTC_PERIPH, ESP_PD_OPTION_ON);
  esp_sleep_enable_timer_wakeup(60*1000*1000);  // 60 seconds
  esp_deep_sleep_start();
}

void loop() {
  // none
}

The first step calls rtc_gpio_init(gpio_num_t gpio_num) with the GPIO pin number to the initialize the pad for an analog/RTC function. Next, rtc_gpio_set_direction(gpio_num_t gpio_num, rtc_gpio_mode_t mode) is used to set the pin as output. Finally rtc_gpio_set_level(gpio_num_t gpio_num, uint32_t level level) is used to set the pin output as either HIGH (1) or LOW (0).

After the pin setup and toggled, a delay of 5 seconds is introduced before setting the pin to the value needed during Deep Sleep. Note that the ESP_PD_DOMAIN_RTC_PERIPH is enabled prior to setting the wake up timer and entering Deep Sleep. After waking from Deep Sleep, setup() is repeated again.

Although this approach worked well, I was trying to save 5uA on an external peripheral. By enabling the RTC peripheral that includes the ULP co-processor, I added about 100uA+ to the ESP power. So in the end I didn’t use this approach.

The key to setting an ESP32 output to a known state during Deep Sleep is to select an RTC_GPIO, initialize and operate the pin using RTC_GPIO_* calls, and enabling the RTC peripheral power domain prior to entering Deep Sleep.

MIFARE CLASSIC® 1K SECTOR TRAILER ACCESS BITS

Radio Frequency Identification (RFID) has become an effective, low cost, contactless method of transferring data between a tag and reader. A reader is a device that has one or more antennas that emits radio waves. These radio waves energize a close proximity passive tag allowing for the exchange of data between the tag and reader. Some common RFID applications include inventory management, asset tracking, loyalty cards, fare cards, employee cards, and access control. The radio wave frequency affects the distance between the tag and reader.

  • Low-Frequency 30kHz to 500kHz (typical 125kHz) range few inches to less than 6 feet.
  • High-Frequency 3MHz to 30MHz (typical 13.56Mhz) range few inches to several feet.
  • Ultra High-Frequency 300MHz to 960MHz (typical 433MHz) up to 25+ feet.
  • Microwave 2.45GHz up to 30+ feet.

The MIFARE Classic® 1K is a common low cost RFID tag that operates at 13.56MHz. These tags come in key card and keychain styles and costs less that $1 each in low quantities. As the 1K indicates, this tag stores 1K bytes of data. For the reader you can use a standard product like the ACR122U that has a USB connection to your computer. If you are making your own embedded system then the RC522 module is a simple, low cost reader module that interfaces to a processor using SPI.

The MIFARE Classic® 1K tag is organized into 16 sectors (0 – 15) with each sector containing 3 data blocks (blocks 0-2) and 1 sector trailer (block 3). Each data block/sector trailer has 16 bytes (16 sectors * 4 blocks/sector * 16 bytes/block = 1024 bytes). Not all bytes are available for user data. Sector 0, data block 0 is reserved for manufacturing data and each sector trailer can contain up to 7 user data bytes if key B isn’t being used. If only data blocks are used then 752 bytes are available for user data.

MIFARE Classic® 1K Data Organization

Manufacturer block (sector 0, block 0, address 0, 16 bytes) is programmed and write protected during product test. Data blocks are configurable as either read/write or value blocks as defined by the access bits in the sector trailer. Value blocks have special commands such as increment and decrement for direct control of stored values, which are helpful in electronic purse applications.

The sector trailer is the last block of the sector. Each sector trailer contains:

  • secret keys A (bytes 0-5) and B (bytes 10-15), which when protected from reading returns ‘0’
  • access conditions for all four sector blocks (bytes 6-8)

All keys are set to 0xFFFFFFFFFFFF at chip delivery and key A is never readable.

Sector Trailer Byte Definitions

Access bits control the access conditions for every data block and sector trailer in the given sector. Access control is defined by 3 bits for each block, which are stored in the sector trailer bytes 6-8 (3 bits/block x 4 blocks/sector = 12 bits/sector * 2 for true and inverted values = 24bits/sector = 3 bytes/sector). Access control limits the ability to read or write sector areas including the sector trailer as well as defining data block’s functions (read/write vs. value block). Formatting of bytes 6-8 is somewhat complex. These three bytes are formed by combining the access bits values of the four sector blocks as shown in the next figure (e.g., bit C22 is the C2 bit value for block 2 within the sector).

Access Bits Byte Definition

Conditions for sector trailer access are defined in the table below. Access control includes the ability to write key A (reading key A is never allowed), read and write key B, and the ability to read and write access bits. For example if you never want to write either key A or key B, but you still want to change the access bits in the future, then C1C2C3 = 101 (5) is a good selection. With this access setting you can never read or write either key, but you can still read the access bits using either key A or key B and write the access bits using key B. The factory default value is C1C2C3 = 001 (1), where key A is used for read and write access to all sector trailer values.

Sector Trailer Access Conditions

A similar table is used to configure the sector data blocks access bits. Access conditions include read, write, increment, decrement/transfer/restore. If you want to only read a data block using only key B, then C1C2C3 = 101 (5) could be used. Note that if key B is readable (set by the sector trailer access bits), it can’t be used for access control (see note [1]).

Data Block Access Conditions

Unless you are using a tag reader with support software, the calculation of the access control bytes is a little tedious. I have created an Excel spreadsheet where the user selects each blocks access bits integer decimal values (unshaded table area) using the appropriate tables (C1C2C3) and the access bits byte values are automatically calculated (B6 B7 B8).

Excel Worksheet to Simplify Access Bits Byte Calculation

This has been a quick discussion on setting the MIFARE Classic® 1K tag access bits. If you want to learn more about this tag, Sanga Chidam YouTube channel has excellent video tutorials on the MIFARE Classic® 1K tags. All figures and tables in this post are from the NXP MF1S503X datasheet.

Arduino Tilt & Laser Distance Finder

A middle school teacher reached out looking for a firmware developer to create a tilt and laser range finder for classroom use to encourage STEM education. This looked like a fun project and appeared straight forward. The teacher had already selected, purchased, and assembled the hardware into a demonstration system for his classroom.

The hardware included:

  • Nano 33 BLE
  • Nextion NX4024T032 basic touch display (400×240, 3.2″ display)
  • Laser range module
  • MB102 power supply
  • 12V AA battery pack (AA cell used for on/off switch)
Laser Distance Finder and Tilt Measuring Device

The Nano 33 BLE has an Inertial Measurement Unit (IMU) to support tilt measurement and the laser range module provided distance information via a serial interface.

The laser module interface documentation was minimal and some test code was created to understand the control and response formats. Second I had planned on using ITEADLIB library to interface to the Nextion display, but the library doesn’t support Nano 33 BLE. So I had to generate code to interface to the Nextion display.

The client provided graphic for the tilt gauge and battery status and conceptual functions and screens. The final system had three screens:

  • Control and measurement used to start/stop measurements, display current measurement data (distance and tilt), and show battery status. It also had buttons to see a previous measurement list and go to the settings page.
  • Measurement list that shows the last 10 measurements in current units.
  • Settings page was used to change tilt and distance calibration offsets, change screen brightness, and toggle units between feet-inches, inches, and millimeters.

On the control and measurement screen there were three primary firmware calculations that were needed, distance measurement, tilt angle, and battery voltage percentage. The only control function was to turn the distance/tilt measurement on and off that used a multi-state Nextion button object.

Distance Calculation

The laser distance module is a self contained system where control and data used an asynchronous start/stop protocol at 115200 baud, 8-N-1. The laser module had both single and multiple (continuous) measurement modes. I used the multiple measurement mode where the module once enabled, continued to send measurements so the system could be pointed and adjusted as needed before stopping the measurement and storing the results.

While in this measurement mode, the distance was updated whenever a new measurement was received through the serial interface. The message was decoded and converted to the display string using the user selected units (ft-inches, inches, or mm). All data was stored in the firmware in inches and converted when needed.

Tilt Calculation

Tilt was updated whenever the Inertial Measurement Unit (IMU) had a new measurement. The interface to the LSM9DS1 IMU used an Arduino library. The IMU x-axis is inline with the laser module. I used all three axis in the calculation and applied the classical method of rectangular to spherical conversion to find the tilt. The key assumption was the only acceleration is due to gravity.

g_tilt = (180.0*acos(x/sqrt(x*x+y*y+z*z))/M_PI) - 90;  // +/- 90 degrees

Battery Percentage Calculation

A low current voltage divider was used to estimate the remaining battery level. Based on the voltage a percentage was calculated. On the Nextion display a progress bar was used to show the amount of remaining battery and the color was changed based on the level between green (50% or greater), yellow, and red (15% or less). The battery level was updated based on a programmable timer value.

Nextion Display

The Nextion Display was developed using the Nextion’s HMI software. Buttons used images to reflect on, off, settings, save, and back. The Nextion display interface is serial and the protocol is defined in the user documentation. Below is a sequence that sets the length of the progress bar, sets the color, and writes the text value of the battery percentage.

  nextionSerial.print("j0.val=");              // progress bar
  nextionSerial.print(String(100-intPerCent));
  nextionSerial.print("\xFF\xFF\xFF");

  if(percentage < 15) {
    nextionSerial.print("j0.bco=63488");       // progress bar red
    nextionSerial.print("\xFF\xFF\xFF");    
  }
  else if (percentage >= 50) {
    nextionSerial.print("j0.bco=1024");       // progress bar green
    nextionSerial.print("\xFF\xFF\xFF");        
  }
  else {
    nextionSerial.print("j0.bco=65504");       // progress bar yellow
    nextionSerial.print("\xFF\xFF\xFF");    
  }
  
  nextionSerial.print("t3.txt=");       // text value
  nextionSerial.print("\"" + String(intPerCent) + "%" + "\"");
  nextionSerial.print("\xFF\xFF\xFF");

Saving Operating Parameters

The Nano 33 BLE does not have EEPROM. The only non-volatile memory is flash. For this project the user wanted to store the units and offsets between power cycles. I looked at several libraries and found one designed to store parameters in flash by Dirk Frehiling on Github. The library works with a data structure defined by the programmer (typedef struct) and uses writePrefs and readPrefs object methods.

// cal flash data structure
typedef struct flashStruct {
  float calDistance;        // inches (always)
  float calTilt;            // degrees
  enum outputType outUnits; // units
} calibrationData;

The project has some other nice features like going into a power down mode after inactivity and displayed fractions of an inch as a fraction for measurements in FT-IN, and INCHES. One future improvement is to increase the accuracy of the tilt measurement using more advance calibration techniques.

NORDIC nRF52840 GPIO High Drive

I recently had a project using the Adafruit Feather nRF52840 Express to control a 2N2222 transistor being used as a high power switch. The nRF52840 SoC is a higher-end Bluetooth 5.2 SoC supporting Bluetooth Low Energy, Bluetooth mesh, NFC, Thread, and Zigbee. It has a 64MHz Arm Cortex-M4 with FPU, 1MB Flash, 256KB RAM and all the standard microcontroller features including UART, SPI, TWI, PDM, I2S, QSPI, PWM, and 12-bit ADCs. Adafruit has created a board support package for the Arduino development environment.

After building the code and making a test circuit with a 620 ohm base resistor, I measured the nRF52840 VOH and the voltage was much lower than expected. Reviewing the nRF52840 datasheet the IOH for standard drive is a minimum of 1mA and a maximum of 4mA. I was exceeding the GPIO pin guaranteed current drive capability.

The nRF52840 is an interesting microcontroller where you can control the GPIO drive between standard, high, and disconnect (open). You can specify both IOH and IOL and they can be different. The RW DRIVE parameter is set in the PIN_CNF[n] register as specified in the nRF52840 Product Specification v1.2. The high drive for a 3.3V VDD is a minimum of 6mA for both IOH and IOL.

First I needed to find the correct GPIO pin [n] value to set the drive parameters. Most of the parameters are set when creating the PWM object, but there is no method to set the RW DRIVE parameter. To find the correct pin number I needed to review variant.h and variant.cpp files in the directory containing the board support package …\packages\adafruit\hardware\nrf52\0.22.0\variants\feather_nrf52840_express.

I was using the Feather A0 pin, which is connected to the nRF52840 P0.04 pin. In variant.h file A0 is mapped to pin 14 (D14). From variant.cpp D14 is mapped to pin 4. This is the [n].

To set the RW DRIVE requires either writing directly to the register (NRF_GPIO->PIN_CNF[4] = 0x203) or use a call to nrf_gpio_cnf with the desired parameters. See the file nrf_gpio.h for enum types and support functions. The following call was made to set VOH to high drive and VOL to standard drive (S0H1). Once this change was made the VOH was well within specification when turning the transistor switch on.

nrf_gpio_cfg(4, 
             NRF_GPIO_PIN_DIR_OUTPUT, 
             NRF_GPIO_PIN_INPUT_DISCONNECT, 
             NRF_GPIO_PIN_NOPULL, 
             NRF_GPIO_PIN_S0H1, 
             NRF_GPIO_PIN_NOSENSE);

Nextion Touchscreen with ESP32

Nextion has a nice series of touch displays that make a very good human machine interface (HMI) solution for embedded products. The interface combines an onboard processor and memory with a touch display. Nextion has developed a software editor to support HMI GUI development.

The Nextion HMI editor has drag and drop components to create your user interface. The display is connected via TTL serial (3V3) RX/TX and requires a 5V/GND power connection with enough current to run the display.

The device I used was part of the Basic Series, NX3224T024, which is a 2.4″, 320×240, resistive touch panel. The document is not clear on which wires are the TX and RX. I found the Nextion TX is the blue wire and the RX the yellow wire. Since the original post I have found documentation showing the interface is 3V3 compatible and will accept 5V on the RX.

For my application I needed a method for a user to configure the embedded system. Instead of using a serial port I selected the Nextion touchscreen. The application was hosted on an ESP32 and code was developed using the Arduino IDE. I found the itead library, which implemented all of the objects I needed in version v0.9.0. I had to modify some of the files in the library to work properly with the ESP32. In NexUpload.cpp I moved the include software serial #include to be within the define block USE_SOFTWARE_SERIAL (makes sense). I also had to modify the NexHardware.cpp NexInit function to assigned the hardware serial pins I used (had to move Serial1 pins due to conflict with flash control).

// NexUpload.cpp
//#define USE_SOFTWARE_SERIAL
#ifdef USE_SOFTWARE_SERIAL
#include <SoftwareSerial.h>
SoftwareSerial dbSerial(3, 2); /* RX:D3, TX:D2 */
#define DEBUG_SERIAL_ENABLE
#endif
// NexHardware.cpp
bool nexInit(void)
{
    bool ret1 = false;
    bool ret2 = false;
    
    dbSerialBegin(9600);
    nexSerial.begin(9600,SERIAL_8N1, 32, 33);	// modified for serial1 I/O
    sendCommand("");
    sendCommand("bkcmd=1");
    ret1 = recvRetCommandFinished();
    sendCommand("page 0");
    ret2 = recvRetCommandFinished();
    return ret1 && ret2;
}

To build the ESP32 Nextion interface there are basically 5 steps after you create the HMI using the Nextion editor.

  • Define objects
  • Create an object listen list
  • Create object callbacks (what to do on touch screen events)
  • Attach callbacks to objects
  • Use nexLoop to monitor the Nextion device

Defining the object requires information from the Nextion HMI editor. To define an object you need the object name, page, and id number. Watch out when editing Nextion pages, ids can change. The listen list is a NexTouch type array of pointers to the objects you created that have the events you are interested in. The callbacks are actions to take based on Nextion events (button push, release, etc.). Attaching callbacks associates the callback routine with an object and event. The object method attachPop() is used when attaching a callback for a button release.

So putting it all together. For a MIDI project I had multiple parameters that could be modified, e.g. MIDI channel number. The parameters were all numerical values so I create a change page that allowed a user to increase or decrease the value by pushing a plus or minus button. Once finished, the value was updated.

Nextion Parameter Change Page

The parameter page had five objects, a title (text), value (numeric), and buttons for plus, minus, and done. The title was static and loaded with the page. The parameter value was also loaded showing the current parameter value. All objects except the title and value were setup for “Touch Release Event” to “Send Component ID”, which means when the button is pushed and then released, a serial string is transmitted with the Nextion object page, id, and name. The protocol is handled by the itead Nextion library.

Defining the objects for the parameter change page used the itead library definitions. These objects were on my Nextion page 6. The library parameters are <Object>(<page>,<id>,<name>).

// Define Nextion Objects
// page 6
NexButton minusChange         = NexButton(6,4, "b1");
NexButton plusChange          = NexButton(6,5, "b2");
NexNumber parameterValue      = NexNumber(6,2, "n0");
NexButton setParameter        = NexButton(6,3, "b0");
NexText parameterName         = NexText(6,1, "t0");

Next these objects were added to the listen list. The reduced version showing the page 6 objects is shown below. Remember to put a NULL at the end of the list. Note that I didn’t setup events for the parameter name or value. Only the plus and minus button that changed the parameter and a done button to set the new value were setup for events.

// Listen List
// object list for touch screen
NexTouch *nex_listen_list[] = {
  // page 6
  &minusChange,
  &plusChange,
  &setParameter,
  NULL
};

The call backs are the actions to perform when the event occurs for that object. For the plus and minus the parameter value is read from the Nextion object, checked against a max/min value, and updated accordingly. The Done button updates the parameter value to the current page value and returns to the calling page. Global variables were used for the min, max, and return information.

// Callbacks
// page 6
void minusPopCallback(void *ptr) {
  uint32_t number;
  parameterValue.getValue(&number);
  if (number > minParameterValue)
    parameterValue.setValue(number - 1);
}
void plusPopCallback(void *ptr) {
  uint32_t number;
  
  parameterValue.getValue(&number);
  if (number < maxParameterValue)
    parameterValue.setValue(number + 1);
}
void setParameterPopCallback(void *prt) {
  uint32_t getValue;
  // update variable that is changing
  parameterValue.getValue(&getValue);
  *modifyParameter = (int)getValue;
  // go back to last page
  returnPage->show();
  // more stuff based on returning page
}

Attaching the callbacks for the release event uses the attachPop() object method. The parameters are the callback function and object. If I had setup the touch event for a push, then the method is attachPush().

// Attach Callbacks
void setupNextion (void) {
  // page 6
  minusChange.attachPop(minusPopCallback, &minusChange);
  plusChange.attachPop(plusPopCallback, &plusChange);
  setParameter.attachPop(setParameterPopCallback, &setParameter);
}

Finally, once everything is setup and initialized, use nexLoop with the listen list to handle the interface to the Nextion touch screen. The nexLoop polls the serial interface and is non-blocking, so my listener was setup as a task.

// Monitor Nextion Interface
// task
void getControl(void * parameter) {
  for(;;) {
    nexLoop(nex_listen_list);
    vTaskDelay(50 / portTICK_PERIOD_MS);
  }
}

Overall the interface was very successful and I was happy with the results. The project had 7 different pages that required almost 900 lines of code. I’m sure there are more efficient ways of coding this interface, which I will discover as I continue to work with Nextion touchscreens.

Arduino SD Card Reader

I recently had a project that required having multiple files that were used to control an animatronics display. Each file was a scene for the display and the code simply would play 1 scene, pause, and then play the next scene.

I used the Adafruit MicroSD card breakout board. This assembly is inexpensive, works with in either 3V or 5V systems, and has an SPI interface. A standard Arduino SD library was used for access. I used the MicroSD card with both a Nano and ESP32.

The SD library supports FAT16/FAT32 file structures. So preparing the microSD card with the file used a Windows 10 computer with a SD reader. The card was formatted and the files were copied.

Accessing the files were simplified using the Arduino SD library. Using root (declared as File) that was pointed to the root directory (“/”) the openNextFile() method was used to get the next filename to use. When we were at the end of the directory, a rewindDirectory() was performed. The filename was then checked for the correct extension.

showFile = root.openNextFile();   // get next file
if (!showFile) {                  // end of directory start over
  root.rewindDirectory();         // beginning
  showFile = root.openNextFile(); // file
}
filename = showFile.name();       // check filename ends in ".BIN"
filename.trim();                  // remove whitespace
filename.toUpperCase();           // all upper case
if(filename.endsWith(".BIN")) {   // check for bin file
  break;    // found good file  
}
else {
  showFile.close();               // close unneeded file
}

Bytes were read from the file using the read() method. It should be noted that the documentation states that EOF is returned at the end of the file. Actually the number of bytes read is returned. When the value is zero (0), then the end of file was encountered.

I used the microSD card with both a Nano (5V) and ESP32 (3V3) and worked without any issues on both systems. For my application I had to read a small buffer (3 bytes) at a 30 frames per second rate (33.3 milli-seconds).

Finding Unknown Resistor Value using Voltage

In the world of sensing, there are many sensors that change their resistance value based on the environment. Knowing the sensor resistance provides a measurement of the environment being measured. These variable resistor sensors include:

  • Thermistor – a variable resistor that changes value with the surrounding temperature changes. There are two types: negative temperature coefficient (NTC) and positive temperature coefficient (PTC). The NTC thermistor decreases in value when the temperature increases the the PTC thermistor increases in value when the temperature increases.
  • Magneto Resistor – a variable resistor that changes value when a magnetic field is applied. When the magnetic fields increases, the resistance increased. When the magnetic field decreases, the resistance decreases.
  • Photoresistor – a variable resistor that changes value based on light energy. The photoresistor resistance decreases when light energy is increased and increases when light energy is decreased.
  • Humistor – a variable resistor that changes value based on humidity.
  • Force Sensitive Resistor – a variable resistor that changes values based on the force that is applied.

Thermistors are variable resistors that are more sensitive to temperature changes then a standard circuit resistor. The simple first order thermistor relationship between resistance and temperature is:

ΔR = kΔT, where
ΔR is change in resistance (in ohms)
Δ is change in temperature (in kelvin)
k is first-order temperature coefficient (in ohms/kelvin)

In general the first order approximation is only accurate over a limited temperature range. The Steinhart-Hart equation is a widely used third order approximation that improves accuracy to less than 0.02 oC over a much wider temperature range.

where
T is absolute temperature (in kelvins)
R is the resistance (in ohms)
a, b, and c are coefficients

NTC thermistors can also be characterized with the Β (beta) parameter equation, which is just a specialized case of the Steinhart-Hart equation.

where
T is absolute temperature in kelvins
T0 is 298.15 K (25 oC)
R0 is resistance at T0
R is the resistance

Having the B parameter and measuring the thermistor resistance, the temperature can be determined. But most embedded systems don’t measure the resistance directly. So the question is how do we measure the thermistor resistance. The answer is to use a voltage divider. Measuring the voltage divider voltage, which is common using analog to digital converters, gives us a way to get the thermistor resistance.

Remember that a voltage divider is two series resistors in this case connecting power and ground. The voltage between the two resistors is given by:

NTC Thermistor Voltage Divider

VOUT = VIN x (R1 / (R1 + R2))
R2 = R1 x (VIN/VOUT – 1), where
R2 = unknown thermistor resistance (in ohms)
R1 = known resistance (in ohms)
VIN = known input voltage (in V)
VOUT = measured voltage between resistors (in V)

Generally NTC thermistors have a nominal resistance at 25oC. Most common is either 10K or 100K ohms. When picking the known resistor R1, the value should match the nominal thermistor resistance, e.g. for a 100K thermistor, R1 should be 100K.

Using an embedded controller like an Arduino UNO or Nano, the code is very simple to convert the sensed input voltage to the thermistor resistance, to a temperature as shown in following code segment.

  // in setup, one time calculation
  Rinf = NTCRESISTOR * exp(-1*BETA/298.15);


  // in Arduino loop
  tempIn = analogRead(TEMPPIN);  // 0 to 1023 values

  // find thermistor R
  // SERIESRESISTOR = R1, 1023.0 = VIN, tempIn = VOUT
  Rth = SERIESRESISTOR * ((1023.0/tempIn) - 1);
  // calculate temp in K and convert to C
  tempC = BETA/(log(Rth/Rinf)) - 273.15;

One final item to consider with a voltage divider is the input impedance of the measuring device. To limit the impact of input impedance on circuit performance, generally you want the input impedance to be at least 10 times the value of R1 in the circuit above. The input impedance is in parallel with R1 so if the input impedance is only 100K, then the effective value of R1 in our circuit is only 50K, which greatly affects the measurement and calculations.

Op Amp Voltage Follower

One way to solve this problem is to use a voltage follower op amp circuit. This circuit provides unity gain (voltage divider Vout equal op amp Vout), has a low output impedance, and very large input impedance. It is important to select an op amp that has stable unity gain.

MOL-AU5016 MP3/WAV Player

I recently had a project where a client wanted to interface an Arduino Nano and ESP32S with MDFLY Electronics AU5016 Embedded SD/SDHC Card MP3/WAV Player Module. The player is controllable using either a digital or parallel interface. It’s features from the datasheet are:

AU5016 Assembly without Headers
  • High performance 32Bit CPU
  • High quality on-chip stereo DAC
  • Decodes MP3/WAV/APE audio format
  • Supports bitrate from 32Kbps to 320Kbps
  • Supports MicroSD/HC memory card up to 32GB
  • Low-power operation
  • Ultra-low background noise
  • TTL serial interface
  • Input voltage: 5VDC
  • Compact design

Some of the limitations of the AU5016 include a maximum of 200 tracks (files) stored/used on the self contained SD card, some of the digital interface commands are required to be repeated until the proper response is received, 5VDC only, and the datasheet is missing some key electrical properties (e.g. Busy IOH). The good stuff, standalone audio playback, works with multiple file types, high performance, and very compact.

I used the digital interface with the Arduino Nano and ESP32S. The digital interface uses start/stop protocol at a default 9600 baud 8N1. The signal levels are TTL (5V only). There is a discrete Busy signal when audio is playing. All of the commands are a single byte.

For this application the AU5016 contained the audio files on an SD card while the Nano/ESP32S SD card contained control information. The control and audio are time synchronized using a third party application. When the control starts the audio is also started. What clock drift there is between the processor and AU5016 is not noticeable in this application’s 2 minute window.

For the Arduino code interface I created an C++ object. This simplified using the AU5016 as typical in the OOP environment. Differences between the Nano and ESP32S was the object used SoftwareSerial on the Nano while the ESP32S used the HardwareSerial. Thankfully these objects have similar interfaces so the code changes were minimal. The object I provided implemented most of the AU5016 commands.

AU5016 Object Definition

// AU5016 object class
class AU5016 {
  public:
    AU5016(int uartNum, int RXPin, int TXPin, int BusyPin); // AU5016 object
    int StartTrack(int track); // starts playing track, error return
    void Stop(void);           // stops tracking playing
    int SetVolume(int level);  // sets volume level, returns volume level
    int VolumeUp(void);        // increases volume level + 1, returns volume level
    int VolumeDown(void);      // decreases volume level -1, returns volume level
    void Mute(void);           // mutes output
    int PlayPause(void);       // pasues play track, un-pauses track, error return
    int SetEQ(int EQ);         // sets EQ, returns error
    int RepeatMode(int Mode);  // sets repeat mode, return error
    int TrackAfterPower(int Mode);  // sets track to play after power on, return error
    int SetBusyStatus(int Mode);    // sets busy output active high or low, return error

  private:
    HardwareSerial *_AudioSerial;   // UART interface to AU5016
    SemaphoreHandle_t  _sema_v;     // multi task access control
    int _Busy;                      // busy pin
    int _audioSendCommand(int cmd); // send a command, return response
    int _audioGetResponse(void);    // get command response, return response
};

Hardware interfacing to the AU5016 for the Nano was simple since both devices are 5V. For the ESP32S, although in input voltage is 5V, the processor and it’s IO is actually 3.3V. I used level TXS0108E translator between the ESP32 and AU5016. Luckily the SD card used with both processors works at either 5V or 3.3V.

Issues

I only encountered one real issue working with the AU5016. I originally use a 32GB SDHC formatting FAT32 for the audio. I couldn’t get the AU5016 to recognize the card. The response was 0xAB, No Memory card. Working with MDFLY tech support they recommended working with a smaller SD card. So I tried a 2GB SD FAT16 and 8GB SDHC and both appeared to work.

RTC DS3231 with Ardunio

Most embedded systems require some kind of real time clock for different timing events. Recently a client wanted a chicken coop controller. Central to the implementation is an Adafruit DS3231 Precision RTC Breakout. This board uses Maxim’s DS3231 Integrated Real Time Clock.

The DS3231 is an extremely accurate real-time clock with an integrated temperature compensated crystal oscillator and crystal. This device supports battery backup to maintain timekeeping when main power is interrupted. This device maintains seconds, minutes, hours, day, date, month, and year information that includes leap year corrections. The DS3231 also has two programmable time of day alarms that trigger an interrupt output when the specified time occurs. The DS3231 interface is I2C.

The chicken coop controller included an Ardunio UNO, Adafruit DS3231 precision real-time clock (RTC), Pololu 5V 1A regulator, 2-channel relay module, AC light dimmer (forward phase) module, 12V linear actuator, and a 12V battery. The Ardunio sketch was to:

  • At sunrise retract the linear actuator for 3 minutes.
  • 1-hour after sunrise turn on lights at 100% brightness
  • Leave lights at 100% brightness for 12.5 hours, then gradually dim over a 1-hour period.
  • At sunset extent the linear actuator for 3 minutes.

Looking at the requirements, all events except the dimming occur on the minute boundary (sunrise, sunset, actuator time, lights on full time). The DS3231 has two alarms. One alarm works down to the second and the other alarm works down to the minute. The need for an alarm to occur on seconds boundary is driven by the light dimming over a 1-hour period. The light dimming uses the 8-bit PWM control. Using all of the PWM control states (256) over 1-hour period has the PWM value updating every 14 seconds (255 down to 0). Since light dimming needs an alarm to occur every 14 seconds, alarm 1 was selected for light control and alarm 2 for actuator control.

The next alarm time is determined by adding the seconds, minutes, hours, and days to a time. For example if the next alarm is to occur in 3 minutes from now, 3 minutes is added to the current time. An add time function was developed to support this sketch. The time is added to the appropriate parameter and then rollover values are tested and updated. When adjusting months the code continues to loop through rollovers until all adjustments are made.

Function to Add time

// function to add time to input time
void addTime(ts *t, int secs, int mins, int hours, int days) {
  boolean adjustMonths = true;
  
  // add time then adjust for rollovers
  t->sec += secs;
  t->min += mins;
  t->hour += hours;
  t->mday += days; 

  // adjust date/time based on rollovers
  if (t->sec >= 60) {
    t->min += t->sec / 60;
    t->sec %= 60;
  }
  if (t->min >= 60) {
    t->hour += t->min / 60;
    t->min %= 60;
  }
  if(t->hour >= 24) {
    t->mday = t->hour / 24;
    t->hour %= 24;
  }

  // adjust months
  while(adjustMonths) {
    switch(t->mon) {
      case 1:
      case 3:
      case 5:
      case 7:
      case 8:
      case 10:
      case 12:
        if (t->mday > 31) {
          t->mday -= 31;
          t->mon += 1;
          if (t->mon > 12) {
            t->mon = 1;
            t->year += 1;
          }
        }
        else
          adjustMonths = false;
        break;
      case 4:
      case 6:
      case 9:
      case 11:
        if (t->mday > 30) {
          t->mday -= 30;
          t->mon += 1;
        }
        else
          adjustMonths = false;
      case 2:
        if (t->year % 4 == 0) {   // leap year, don't worry about % 400
          if (t->mday > 29) {
            t->mday -= 29;
            t->mon += 1;
          }
          else
            adjustMonths = false;
        }
        else
          if (t->mday > 28) {
            t->mday -= 28;
            t->mon += 1;
          }
          else
            adjustMonths = false;
        break;
    }
  }
}

In setting the alarm the developer must enable all values (seconds, minutes, hours, date) up to the desired match (i.e. if alarm is on a hour value, then seconds, and minutes must also be enabled).

When the time matches the enabled alarm parameters then the DS3231 INT/ pin goes active low. Since the I2C Adruino library uses interrupts to communicate, this sketch polls this DS3231 pin instead of using an interrupt. During the polling each alarm is checked and the proper flag(s) is(are) set.

One final item with the DS3231 is the control register used to enable/disable alarms and set other parameters. This register is not readable. If the alarms or other controls are enabled at different times in the code, then a “shadow” register is needed to maintain the current control register state. For example is you are enabling alarm 2 you don’t know the current state of alarm 1 unless you maintain an internal variable in your code.

Finally the library select to support the DS3231 was ds3231FS by Petre Rodan. This library provided an interface to setting the alarms.