Overview: MicroPython on ESP32 with Ultrasonic Sensor
In this project we will be interfacing HC-SR04 Ultrasonic Sensor with ESP32 using MicroPython Code. We will use Ultrasonic Sensor with ESP32 Board & 0.96″ I2C OLED Display. We will then write a MicroPython Code in uPyCraft IDE. Using the uPyCraft IDE, we can directly upload the firmware to ESP32 Board.
HC-SR04 is an ultrasonic sensor mainly used to determine the distance of the target object. It measures accurate distance using a non-contact technology – A technology that involves no physical contact between sensor and object.
Before proceeding, you can check this Guide: MicroPython on ESP32 using PyCraft IDE – Getting Started. I highly recommend you to follow this guide as it is covers all the basics including setting up the IDE to writing the code & uploading as well.
Bill of Materials
Following are the components required for making this project. All the components can be eaily purchased from Amazon. The components purchase link is given below.
| S.N. | Components Name | Quantity | Purchase Links |
|---|---|---|---|
| 1 | ESP32 Board | 1 | Amazon | AliExpress |
| 2 | 0.96" I2C OLED Display | 1 | Amazon | AliExpress |
| 3 | Ultrasonic Sensor HC-SR04 | 1 | Amazon | AliExpress |
| 4 | Jumper Wires | 5 | Amazon | AliExpress |
| 5 | Breadboard | 1 | Amazon | AliExpress |
Or if you want a combined product then you can purchase the MakePython ESP32 Board from Makerfabs as shown in the image below. The board contains combined ESP32 Chip + 1.3″ I2C OLED Display supports MicroPython.
To learn more about this board and purchase it online, you can visit this link: MakePython ESP32 Board.
HC-SR04 Ultrasonic Sensor
The HC-SR04 is an ultrasonic distance sensor. This economical sensor provides 2cm to 400cm of non-contact measurement functionality with a ranging accuracy that can reach up to 3mm. The HC-SR04 module contains an ultrasonic transmitter, a receiver and a control circuit.
There are only four pins on the HC-SR04: VCC (Power), Trig (Trigger), Echo (Receive), and GND (Ground). This sensor has additional control circuitry that can prevent inconsistent “bouncy” data depending on the application.
To learn more about this sensor and learn its basic application, you can visit this link: Distance Measurement with Ultrasonic Sensor
Interfacing Ultrasonic Sensor HC-SR04 with ESP32 using MicroPython
Here is a circuit diagram for Interfacing Ultrasonic Sensor HC-SR04 with ESP32 using MicroPython Code. The TRIG pin is connected to ESP32 GPIO13 Pin & ECHO pin is connected to ESP32 GPIO12 Pin. Similarly the VCC is connected to 5V & GND is connected to GND.
In case if you are using MakePython ESP32 Board, you can do the following connection as shown in the connection diagram below.
Source Code/Program
The MicroPython Code for using Ultrasonic Sensor with ESP32 has three parts. This is because we need library for HC-SR04 Ultrasonic Sensor and OLED Display.
The three parts includes:
1. SSD1306.py
2. HC_SR04.py
3. Main.py
SSD1306.py
The library to write to the OLED display isn’t part of the standard MicroPython library by default. So, first we need to upload the library to the ESP32 board.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 |
# MicroPython SSD1306 OLED driver, I2C and SPI interfaces from micropython import const import time import framebuf import sys currentBoard="" if(sys.platform=="esp8266"): currentBoard="esp8266" elif(sys.platform=="esp32"): currentBoard="esp32" elif(sys.platform=="pyboard"): currentBoard="pyboard" import pyb # register definitions SET_CONTRAST = const(0x81) SET_ENTIRE_ON = const(0xa4) SET_NORM_INV = const(0xa6) SET_DISP = const(0xae) SET_MEM_ADDR = const(0x20) SET_COL_ADDR = const(0x21) SET_PAGE_ADDR = const(0x22) SET_DISP_START_LINE = const(0x40) SET_SEG_REMAP = const(0xa0) SET_MUX_RATIO = const(0xa8) SET_COM_OUT_DIR = const(0xc0) SET_DISP_OFFSET = const(0xd3) SET_COM_PIN_CFG = const(0xda) SET_DISP_CLK_DIV = const(0xd5) SET_PRECHARGE = const(0xd9) SET_VCOM_DESEL = const(0xdb) SET_CHARGE_PUMP = const(0x8d) class SSD1306: def __init__(self, width, height, external_vcc): self.width = width self.height = height self.external_vcc = external_vcc self.pages = self.height // 8 self.buffer = bytearray(self.pages * self.width) self.framebuf = framebuf.FrameBuffer(self.buffer, self.width, self.height, framebuf.MVLSB) self.poweron() self.init_display() def init_display(self): for cmd in ( SET_DISP | 0x00, # off # address setting SET_MEM_ADDR, 0x00, # horizontal # resolution and layout SET_DISP_START_LINE | 0x00, SET_SEG_REMAP | 0x01, # column addr 127 mapped to SEG0 SET_MUX_RATIO, self.height - 1, SET_COM_OUT_DIR | 0x08, # scan from COM[N] to COM0 SET_DISP_OFFSET, 0x00, SET_COM_PIN_CFG, 0x02 if self.height == 32 else 0x12, # timing and driving scheme SET_DISP_CLK_DIV, 0x80, SET_PRECHARGE, 0x22 if self.external_vcc else 0xf1, SET_VCOM_DESEL, 0x30, # 0.83*Vcc # display SET_CONTRAST, 0xff, # maximum SET_ENTIRE_ON, # output follows RAM contents SET_NORM_INV, # not inverted # charge pump SET_CHARGE_PUMP, 0x10 if self.external_vcc else 0x14, SET_DISP | 0x01): # on self.write_cmd(cmd) self.fill(0) self.show() def poweroff(self): self.write_cmd(SET_DISP | 0x00) def contrast(self, contrast): self.write_cmd(SET_CONTRAST) self.write_cmd(contrast) def invert(self, invert): self.write_cmd(SET_NORM_INV | (invert & 1)) def show(self): x0 = 0 x1 = self.width - 1 if self.width == 64: # displays with width of 64 pixels are shifted by 32 x0 += 32 x1 += 32 self.write_cmd(SET_COL_ADDR) self.write_cmd(x0) self.write_cmd(x1) self.write_cmd(SET_PAGE_ADDR) self.write_cmd(0) self.write_cmd(self.pages - 1) self.write_data(self.buffer) def fill(self, col): self.framebuf.fill(col) def pixel(self, x, y, col): self.framebuf.pixel(x, y, col) def scroll(self, dx, dy): self.framebuf.scroll(dx, dy) def text(self, string, x, y, col=1): self.framebuf.text(string, x, y, col) def hline(self, x, y, w, col): self.framebuf.hline(x, y, w, col) def vline(self, x, y, h, col): self.framebuf.vline(x, y, h, col) def line(self, x1, y1, x2, y2, col): self.framebuf.line(x1, y1, x2, y2, col) def rect(self, x, y, w, h, col): self.framebuf.rect(x, y, w, h, col) def fill_rect(self, x, y, w, h, col): self.framebuf.fill_rect(x, y, w, h, col) def blit(self, fbuf, x, y): self.framebuf.blit(fbuf, x, y) class SSD1306_I2C(SSD1306): def __init__(self, width, height, i2c, addr=0x3c, external_vcc=False): self.i2c = i2c self.addr = addr self.temp = bytearray(2) super().__init__(width, height, external_vcc) def write_cmd(self, cmd): self.temp[0] = 0x80 # Co=1, D/C#=0 self.temp[1] = cmd #IF SYS : global currentBoard if currentBoard=="esp8266" or currentBoard=="esp32": self.i2c.writeto(self.addr, self.temp) elif currentBoard=="pyboard": self.i2c.send(self.temp,self.addr) #ELSE: def write_data(self, buf): self.temp[0] = self.addr << 1 self.temp[1] = 0x40 # Co=0, D/C#=1 global currentBoard if currentBoard=="esp8266" or currentBoard=="esp32": self.i2c.start() self.i2c.write(self.temp) self.i2c.write(buf) self.i2c.stop() elif currentBoard=="pyboard": #self.i2c.send(self.temp,self.addr) #self.i2c.send(buf,self.addr) self.i2c.mem_write(buf,self.addr,0x40) def poweron(self): pass class SSD1306_SPI(SSD1306): def __init__(self, width, height, spi, dc, res, cs, external_vcc=False): self.rate = 10 * 1024 * 1024 dc.init(dc.OUT, value=0) res.init(res.OUT, value=0) cs.init(cs.OUT, value=1) self.spi = spi self.dc = dc self.res = res self.cs = cs super().__init__(width, height, external_vcc) def write_cmd(self, cmd): global currentBoard if currentBoard=="esp8266" or currentBoard=="esp32": self.spi.init(baudrate=self.rate, polarity=0, phase=0) elif currentBoard=="pyboard": self.spi.init(mode = pyb.SPI.MASTER,baudrate=self.rate, polarity=0, phase=0) self.cs.high() self.dc.low() self.cs.low() global currentBoard if currentBoard=="esp8266" or currentBoard=="esp32": self.spi.write(bytearray([cmd])) elif currentBoard=="pyboard": self.spi.send(bytearray([cmd])) self.cs.high() def write_data(self, buf): global currentBoard if currentBoard=="esp8266" or currentBoard=="esp32": self.spi.init(baudrate=self.rate, polarity=0, phase=0) elif currentBoard=="pyboard": self.spi.init(mode = pyb.SPI.MASTER,baudrate=self.rate, polarity=0, phase=0) self.cs.high() self.dc.high() self.cs.low() global currentBoard if currentBoard=="esp8266" or currentBoard=="esp32": self.spi.write(buf) elif currentBoard=="pyboard": self.spi.send(buf) self.cs.high() def poweron(self): self.res.high() time.sleep_ms(1) self.res.low() time.sleep_ms(10) self.res.high() |
First open a new file in uPyCraft IDE paste the above code. Save the file as a name “SSD1306.py“. Click the “Download & Run” Icon. This will upload the file to the ESP32 board.
The uPyCraft console window should the following message.
Now you can import the SSD1306 Library and use it on the Code Part.
HC_SR04.py
Now open a new tab and upload the following code. The code will upload the Ultrasonic Sensor HC_SR04 Library to ESP32 Board.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 |
import machine, time from machine import Pin class HCSR04: """ Driver to use the untrasonic sensor HC-SR04. The sensor range is between 2cm and 4m. The timeouts received listening to echo pin are converted to OSError('Out of range') """ # echo_timeout_us is based in chip range limit (400cm) def __init__(self, trigger_pin, echo_pin, echo_timeout_us=500*2*30): """ trigger_pin: Output pin to send pulses echo_pin: Readonly pin to measure the distance. The pin should be protected with 1k resistor echo_timeout_us: Timeout in microseconds to listen to echo pin. By default is based in sensor limit range (4m) """ self.echo_timeout_us = echo_timeout_us # Init trigger pin (out) self.trigger = Pin(trigger_pin, mode=Pin.OUT, pull=None) self.trigger.value(0) # Init echo pin (in) self.echo = Pin(echo_pin, mode=Pin.IN, pull=None) def _send_pulse_and_wait(self): """ Send the pulse to trigger and listen on echo pin. We use the method `machine.time_pulse_us()` to get the microseconds until the echo is received. """ self.trigger.value(0) # Stabilize the sensor time.sleep_us(5) self.trigger.value(1) # Send a 10us pulse. time.sleep_us(10) self.trigger.value(0) try: pulse_time = machine.time_pulse_us(self.echo, 1, self.echo_timeout_us) return pulse_time except OSError as ex: if ex.args[0] == 110: # 110 = ETIMEDOUT raise OSError('Out of range') raise ex def distance_mm(self): """ Get the distance in milimeters without floating point operations. """ pulse_time = self._send_pulse_and_wait() # To calculate the distance we get the pulse_time and divide it by 2 # (the pulse walk the distance twice) and by 29.1 becasue # the sound speed on air (343.2 m/s), that It's equivalent to # 0.34320 mm/us that is 1mm each 2.91us # pulse_time // 2 // 2.91 -> pulse_time // 5.82 -> pulse_time * 100 // 582 mm = pulse_time * 100 // 582 return mm def distance_cm(self): """ Get the distance in centimeters with floating point operations. It returns a float """ pulse_time = self._send_pulse_and_wait() # To calculate the distance we get the pulse_time and divide it by 2 # (the pulse walk the distance twice) and by 29.1 becasue # the sound speed on air (343.2 m/s), that It's equivalent to # 0.034320 cm/us that is 1cm each 29.1us cms = (pulse_time / 2) / 29.1 return cms |
Main.py
After downloading the SSD1306.py & HC_SR04.py file to the ESP32 Board, you can now upload the main code. To do that open another file and paste the below code. Save it as a name “main.py“.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
from hcsr04 import HCSR04 from machine import Pin,I2C import ssd1306 i2c = I2C(scl=Pin(5), sda=Pin(4), freq=100000) #Init i2c lcd=ssd1306.SSD1306_I2C(128,64,i2c) sensor = HCSR04(trigger_pin=13, echo_pin=12,echo_timeout_us=1000000) try: while True: distance = sensor.distance_cm() print(distance) lcd.fill(0) lcd.text("Distance:",30,20) lcd.text(str(distance),30,40) lcd.show() except KeyboardInterrupt: pass |
Testing the Ultrasonic Range Finder
Once the MicroPython code is uploaded to ESP32 Board, the Ultrasonic Sensor will start showing the distance in cm. You can check the working of the sensor by placing something in front of the sensor.
Ultrasonic range finders are fun little sensors that can measure distance. You can use them to find the distance to an object or to detect when something is near the sensor like a motion detector. Because they use sound to measure distance, they work just as well in the dark as they do in the light. It can measure distances from 2 cm up to 400 cm with an accuracy of ±3 mm.
