Flashing UPDI devices with pymcuprog¶
If neither avrdude nor zflasher are viable
choices, but the system is capable of running Python, then pymcyprog
may be
a good alternative. The main limitation of pymcuprog
is that it only
supports UPDI programmers (e.g. CH340).
Installation¶
Install Python¶
To run pymcyprog
, first install Python. Use Python 3.x as older versions are
no longer supported.
Windows¶
On Windows, there are two main ways to get Python:
Use the Windows installer from Python
Install from the Microsoft Store
Either method will result in a working Python installation.
Linux¶
Many Linux distributions come with Python installed as a part of the base OS,
but those that do not should also have it available by their packaging system
(e.g. apt
, dnf
, etc.).
In nearly all cases python should be on the path already so it should be ready
to use as-is. It may be called python3
or versioned in a more specific way.
macOS¶
Download the macOS installer from Python and run it.
The installer adds it to the system path automatically, though it may be necessary to restart a terminal session to pick up the change.
Install pymcuprog¶
After installing python, open a command prompt and install pymcuprog:
$ pip3 install pymcuprog
Note
Depending on the system, the pip
command may be OK or it may point to a
different version of Python. It’s safer to use pip3
to ensure it runs the
Python 3.x version.
Note
In some cases the install may trigger prompts to install other required dependencies, e.g. macOS may require development tools, Xcode or similar.
Getting pymcuprog on the Path¶
For Linux and macOS, pymcuprog
should be in the command path automatically.
This is not always the case for Windows, however.
There may be some quirks getting the paths right for pymcuprog
if Python was
installed from the Microsoft Store, since the location for the packages is not
in the path by default.
Try running pymcuprog
from a terminal, PowerShell, or command prompt, if it
prints its usage output, then it’s OK to proceed. Otherwise, check and correct
the path or python issues.
In Explorer, first locate the correct folder. It will be something similar to
C:\Users\<name>\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.9_<id>\LocalCache\local-packages\Python39\Scripts
– Copy that full path.
The correct path will also be found in the output of:
PS> python -c "import sys; print('\n'.join(sys.path))"
The correct item will be the entry similar to the path mentioned previously.
Right click on the Start/Windows button
Click System
Click Advanced System Settings
Click Environment Variables
Find the entry for Path in the User variables section and select it
Click Edit
Add the path to the list (paste it in or type it out)
Click OK, then OK again to close the Environment Variables window
Click OK one more time to close System Properties
pymcuprog Syntax¶
If pymcuprog
is on the path properly, then invoking the command on its own
at a terminal command prompt (e.g. PowerShell, Konsole, Terminal, etc.) will
print some basic information on the syntax.
The pymcuprog
command takes numerous parameters but only a handful are
important for the purposes of working with flashlights:
<action>
ping
Perform a communication test between
pymcuprog
, the programmer, and the controller chip. This does not make any changes to the controller or local system.read
Read the chosen area from the chip and write it to a local file. This is used when making a backup of the current firmware on a controller chip.
write
Write the chosen area on the chip using content from a local file. This is used when updating the firmware on the controller chip to a new version using a local file.
erase
Erase the chosen area on the controller chip.
-d <device>
The type of controller chip (MCU) on the light. Currently this is most likely to be
attiny1616
. In most cases the MCU for a given light is listed in the Anduril MODELS file.-t <tool>
The type of connection to the programmer. When using a programmer such as the CH340 with a serial interface, this will be
uart
.-u <uart>
The serial port through which
pymcuprog
can reach the programmer. For example,com7
or/dev/ttyUSB0
.See also
To locate the correct port, see CH340 Drivers and Serial Port.
-m <memory>
The type of memory to operate on. Only two areas are relevant for most controller chips found on flashlights,
flash
andeeprom
(Controller Chip Storage Areas). The default isflash
and this parameter can be omitted when working with that area.-f <filename>
The firmware filename to read or write. If the file is not in the current directory, include the full path.
When reading, the file will be created or overwritten with the content of the selected area from the controller chip. When writing, the file will be read and used to reprogram the selected area of the controller chip.
--erase
Erase the selected memory area of the controller chip before writing. This is not performed by default, but is a beneficial step.
--verify
Verify the selected memory area of the controller chip after writing. This is not performed by default, but is a beneficial step.
See also
For more details on syntax, see the pymcuprog documentation on PiPI.
Ping the Device¶
The best first test of connectivity to the light is to perform a “ping” which
makes sure that pymcuprog
can communicate with both the programmer and the
controller chip.
For this to work the programmer must be connected to the computer and the probe must be connected to both the programmer and the light. For example, by touching the probe to the flashing pads.
This example runs pymcuprog
as if it is on the path in Windows communicating
with an ATtiny1616 controller through a serial UPDI programmer on COM7
, and
attempts communication with the chip without making any changes:
PS> pymcuprog ping -d attiny1616 -t uart -u com7
The output should look like the following if it’s successful:
Connecting to SerialUPDI
Pinging device...
Ping response: 1E9421
Done.
If there is an error, most likely the probe was not correctly contacting all of the correct pins. Check and correct the probe placement and try again.
Backing Up¶
An important part of the process is making a backup of the firmware in case the new firmware does not work as expected. The old firmware can be written back so the light can be returned to its prior state.
When performing a read operation, pymcuprog
reads the contents of the chosen
area on the controller chip and then stores the contents in a local file.
Change to the directory where the firmware file was downloaded, for example:
PS> cd ~\Downloads
This example reads the firmware from a light (ATtiny1616 controller, serial UPDI
programmer on COM7
) and stores the old firmware in a file named
old-firmware.hex
in the current directory.
PS> pymcuprog read -d attiny1616 -t uart -u com7 -f old-firmware.hex
Updating¶
Change to the directory where the firmware file was downloaded, for example:
PS> cd ~\Downloads
Now write the firmware file. Replace the filename with the correct firmware filename that matches the light.
PS> pymcuprog write -d attiny1616 -t uart -u com7 --erase --verify -f new-firmware.hex