Previously we’ve discussed how to get started with Eduponics mini IDE, if you consider yourself an advanced programmer, you might want to take things one step further using Advance ESP32 tools. We’d like to introduce some advanced tools such as detecting the UART manually and operating the ESP32 with Ampy (an Adafruit Tool) something that can be useful if you want to work outside of the Thonny IDE environment.
Manual work from now on
We strongly suggest you to start with Thonny IDE if you are a complete beginner the following steps will explain about Ampy, Putty and some other tools that can help you install and run scripts manually on your Eduponics kit this might be very useful for advanced users but not so friendly for new users without previous experience.
Connecting to the kit through UART #
Once we have the necessary drivers installed, it’s time to connect to our board through UART for the first time. Firstly, we’ll need to find the UART port.
Baud rate also stands for bits per second and is a number related to the speed of data transmission in a system. The rate indicates the number of electrical oscillations per second that occurs within a data transmission. The higher the baud rate – the higher the transfer rate of bits per second.
In our Eduponics mini kit, the UART baud rate is 115200 which we will use by default to communicate with our ESP32 microcontroller. If we use a different baud rate we might get nonsense or “spaghetti” feedback instead of what we expect the board to print back to us in response.
Detecting USB devices in Mac OSX and Linux #
Run the following command in the terminal to find connected UART devices to make the process easier, make sure only the Eduponics Mini kit is connected to your computer by USB. Else, you might see other unrelated devices that might confuse you.
ls /dev/*usb*
the results should look similar to this:
/dev/cu.usbserial-14310 /dev/tty.usbserial-14310
In our example, the UART name will be “tty.usbserial-14310” which we will use to connect to the Eduponics mini.
Now when we have the right UART name, we can easily run the following command in the terminal to connect to the ESP32 MicroPython command-line interface:
screen tty.usbserial-14310 115200
Of course, you will need to change the number “14310” to the one that shows up on your machine – it might look different. “115200” stands for the communication baud rate we use.
Small tip for alternatives to screen
On Linux, “picocom” or “minicom” may be used instead of “screen”. The USB serial address might also be listed as /dev/ttyUSB01 or a higher increment for ttyUSB. Additionally, the elevated permissions to access the device (e.g. group uucp/dialout or use sudo) may be required.
This can be done by typing the following commands “sudo usermod -a -G dialout $user && sudo chmod a+rw /dev/ttyUSB0”
sudo usermod -a -G dialout $user
sudo chmod a+rw /dev/ttyUSB0Detecting USB devices in Windows #
In Windows it’s a little different, let’s follow the steps below:
- Open Device Manager.
- Click on View in the menu bar and select Show hidden devices.
- Locate Ports (COM & LPT) in the list.
- Check for the com ports by expanding the COM menu option.
Once you’ve located the right COM port, it’s time to download putty to connect to the UART port.
PuTTY is an SSH and telnet client, developed originally by Simon Tatham for the Windows platform. PuTTY is open-source software that is available with source code and is developed and supported by a group of volunteers.
We use PuTTY to communicate through UART with the Eduponics Mini, in OSX or Linux operation systems – a small piece of software called “screen” is already included, that allows us to communicate through UART without the need for external software
You can download Putty from here: Putty’s official website
Once you have Putty installed, you can proceed to enter the COM port that we found earlier in the device manager (it may not necessarily be COM4, it could be a different number) also make sure to set the baud rate as 115200 as we mentioned earlier.
Tick the connection type checkbox as “Serial” once you are ready click the “Open” button to initialize the connection.
Thonny IDE detects the UART name automatically
If you use the Thonny IDE for your programming needs, in the interpeter it will already show you the port name and device information without needing to look for it manually.
Adafruit MicroPython advance ESP32 Tool #
If you are looking for an Advance ESP32 tool, you came to the right place. The Adafruit MicroPython Tool (ampy) – Utility helps you to interact with a MicroPython board over a serial connection. This appreciable utility can be useful to send, read, and run files on our Eduponics mini board with ease.
Ampy is meant to be a simple command line tool to manipulate files and run code on a MicroPython board over its serial connection. With ampy, you can send files from your computer to the board’s file system, download files from a board to your computer, and even send a Python script to a board to be executed. Due to Ampy being a command tool and not a GUI it might not be suitable for every user’s needs. We will consider it an advance ESP32 tool to be used when other GUI tools can’t get the task done.
We can find the ampy GitHub repository here: https://github.com/scientifichackers/ampy
The installation is very straightforward, let’s make sure we have all the prerequisites such as python-pip, pyserial, and python3.
Using Ampy on MacOS or Linux #
in a terminal run the following command:
pip3 install --user adafruit-ampy
Note on some Linux and Mac OSX systems you might need to run as root with sudo:
sudo pip3 install adafruit-ampy
Using Ampy On Windows: #
do the following
pip3 install adafruit-ampy
Installing Ampy from the source #
If you’d like to install from the Github source then use the standard Python setup.py install:
git clone https://github.com/scientifichackers/ampy.git
cd ampy
python3 setup.py install
Ampy advanced ESP32 tools usage information #
Once installed verify you can run the ampy program and get help output:
ampy --help
You should see usage information displayed below:
Usage: ampy [OPTIONS] COMMAND [ARGS]...
ampy - Adafruit MicroPython Tool
Ampy is a tool to control MicroPython boards over a serial connection.
Using ampy you can manipulate files on the board's internal filesystem and
even run scripts.
Options:
-p, --port PORT Name of serial port for connected board. [required]
-b, --baud BAUD Baud rate for the serial connection. (default 115200)
-d, --delay DELAY Delay in seconds before entering RAW MODE (default 0)
--help Show this message and exit.
Commands:
get Retrieve a file from the board.
ls List contents of a directory on the board.
put Put a file on the board.
rm Remove a file from the board.
run Run a script and print its output.
Executing files using Ampy advance ESP32 tools #
To run files with ampy we first need to make a file. let’s make a python script and call it test.py this file can be created in text editor or your IDE / Code editor.
inside the python script let’s write the following:
print("hello world")
Make sure to save it. Once we have test.py file with the print hello world command inside of it, we can run it on our microcontroller using ampy by running the following commands:
Serial port name changed is required
You will need to change the USB Serial port name as it shows on your computer
Changing to the right port name on Mac OSX / Linux:
ampy --port /dev/tty.usbserial-<NUMBER_GOES_HERE> run test.py
Changing to the right port name on Windows:
ampy --port <COM_PORT_NAME_GOES_HERE> run test.py
Once you’ll run the code a response should come back with the text “hello world”
Running doesn’t mean save the code
Running the code on your ESP32 Eduponics Mini board doesn’t save the code inside the board’s memory – it will only execute it. To save the code and run it later, proceed to the following steps where we will explain how to “push” files.
Pushing files to the ESP32 using Ampy #
The Pushing command is very similar to executing (running) files except we put them into our ESP32 device without actually running them. Later on, we can run them directly from the ESP32 board.
How to push files on ESP32 if you have Mac OSX / Linux:
ampy --port /dev/tty.usbserial-<NUMBER_GOES_HERE> put test.py
How to push files on ESP32 if you have Windows:
ampy --port <COM_PORT_NAME_GOES_HERE> put test.py
Again, please do remember you need to change the COM port if you are on windows or type the correct serial number if you are on Linux / OSX.
Getting files from the ESP32 using Ampy #
Getting files is the process of taking a file we have previously pushed into our ESP32 board but for some reason we don’t have it anymore or we changed our local file and want to get the file that is currently inside the board. To do that, we’ll use the “get” command to get the file from the ESP32 board into our local machine.
Getting files from the ESP32 in Mac OSX / Linux:
ampy --port /dev/tty.usbserial-<NUMBER_GOES_HERE> get test.py
Getting files from the ESP32 in Windows:
ampy --port <COM_PORT_NAME_GOES_HERE> get test.py
Please note that “get test.py” has nothing to do with your local file test.py on your machine. By running “get test.py” it will overwrite any existing files named test.py.
Renaming files from the ESP32 using Ampy #
If you want to name it differently (rename the file) add another line at the end to state the new file name as follows:
Renaming ESP32 files on Mac OSX / Linux:
ampy --port /dev/tty.usbserial-<NUMBER_GOES_HERE> get test.py new_test.py
Renaming ESP32 files on Windows:
ampy --port <COM_PORT_NAME_GOES_HERE> get test.py new_test.py
Removing files #
What kind of advance ESP32 tools it would be if we can’t remove files by using it? Sometimes we don’t need the files we pushed earlier into our board, they take up unnecessary flash space and therefore we should delete them. to do so, we can use the “rm” command which stands for removal of existing files on the board
In Mac OSX / Linux:
ampy --port /dev/tty.usbserial-<NUMBER_GOES_HERE> rm test.py
In Windows:
ampy --port <COM_PORT_NAME_GOES_HERE> rm test.py
Note, this will not affect any local file on your machine named “test.py” it will only remove the “test.py” file from the memory of the ESP32 chipset.
Listing files #
The final step will be listing the files, let’s say you previously pushed some files and removed some files and it’s been some time or you’ve got confused about what files we have in the ESP32 board and what files are missing … all of this can be solved with one simple command “ls” which stands for list.
In Mac OSX / Linux:
ampy --port /dev/tty.usbserial-<NUMBER_GOES_HERE> ls
In Windows:
ampy --port <COM_PORT_NAME_GOES_HERE> ls
As you can see, we don’t need to mention any file that’s because we just want to get the name of all the files that already exist on the ESP32 board.
That’s all the Ampy commands that you’ll need, make sure to practice by pushing, getting, removing, and listing files before you move to your own project to avoid mistakes!
Coming up next #
Congratulations! you’ve made your first step in command-line programming, hardware, and the STEM world! By being able to master the advance ESP32 tools and command lines, nothing could withstand the power in your finger tips.
Next, we’ll start by introducing each sensor that is available on top of the Eduponics mini kit. After you’ll master the science behind the sensors and how to program them yourself. We’ll then move on to more advanced examples, combining multiple sensors together to achieve a fully functional IoT plant monitoring system.
Leave A Comment