Hardware design for test device
-
datasheets - all the datasheets for parts used
-
docs - documents about this project
-
firmware - the code for testing and supporting the hardware
-
hardware - the schematics and PCB designs
-
models - Contains 3D models for project
-
photos - image from the project as it progresses
-
productions - files used for manufacturing that are generated from the stuff in hardware
The Firmware is split into 3 categories. Management, User Interface, and Network.
- Management - STM32F072
- User Interface - STM32F405
- Network - ESP32S3
The management chip is responsible for uploading firmware to the stm32 - main chip and the esp32 network chip using a ch340 usb chip.
The management chip receives commands from the usb communication that informs it what chip we are currently uploading. As well as debugging. It is able to receive log messages from the ui and net chips and push them out to the usb interface.
On the first flash you'll need to figure out what device port your hactar is on. You can do this in several ways depending on which operating system you are on. Start by viewing your devices, and then plug in your hactar, and then view your devices again and see what was added to your device list.
-
ls /dev/ttyUSB*
-
Open printers and devices
Find serial com ports
To flash the management chip you'll need to press the boot and reset buttons on the board in the following manner:
Button press order
- Press and hold boot button (left).
- Press and release reset button (right).
- Release boot button.
First flash
- In hactar/firmware/mgmt, enter make upload PORT=<path/to/device>
After flashing the management chip you can run make upload
without specifying the port, and it will be automatically found by the flasher and an attempt to upload will occur, when you see the attempt return to Button press order
- reset - Resets
ui
chip and thennet
chip. Accepts commands. - ui_upload - Puts the management chip into
ui
chip upload mode. (STM32f05) - net_upload - Puts the management chip into
net
chip upload mode. (ESP32S3) - debug - Puts the management chip into debugging mode where serial messages from both
ui
and network chips are transmitted back to the usb interface. This is uni-directional from the management chip to the computer. However, all commands work during this mode. - debug_ui - Only reads serial messages from the
ui
chip. - debug_net - Only reads serial messages from the
net
chip.
-
all
- Builds the target bin, elf, and binary files -
compile
- Builds the target bin, elf, and binary. Output firmware/build/mgmt -
upload
- Uploads the build target to the Management chip using the our custom flasher tool with serial usb-c uploading. See Python Flasher -
upload-stflash
- Uploads the build target to the Management chip using the st-flash tools. Please see st-flash installation for instructions on installing. -
upload_cube_serial
- Uploads the build target to the Management chip using the STM32_Programmer_CLI with serial usb-c uploading. See Installation for instructions on installing the STM32_Programmer_CLI. -
upload_cube_swd
- Uploads the build target to the Management chip using the STM32_Programmer_CLI with st-link using SWD uploading. See Installation for instructions on installing the STM32_Programmer_CLI. -
docker
- Uses docker to compile, flash, and monitor the mgmt chip. By default it will compile the code. To change the functionality, pass a target of the Makefile into the parametermft
when being invoked.- Ex.
make docker mft=upload
- Ex.
make docker mft=monitor
- Ex.
-
docker-clean
- Removes dockere image that was generated when running docker target. -
clean
- Deletes the firmware/build/ui directory. -
info
- Displays the build path, include files, object files, dependencies and vpaths used by the compiler.
Source code
All source code for the Management Chip can be found in firmware/mgmt. Adding C/C++ files in firmware/mgmt/src and firmware/mgmt/inc does require any changes in the makefile.
The User Interface chip is where most of the processing takes place. It utilizes a STM32F405 chip empowered by the STM HAL Library. To generate the baseline HAL Library code and Makefile, ST's CubeMX was used.
Target Overview
-
all
- Builds the target bin, elf, and binary files and uploads the code to the User Interface chip. Output firmware/build/ui -
compile
- Builds the target bin, elf, and binary. Output firmware/build/ui -
upload
- Uploads the build target to the User Interface chip using the st-flash tools. Please see st-flash installation for instructions on installing. -
upload_py
- Uploads the build target to the User Interface chip using the our custom flasher tool with serial usb-c uploading. See Python Flasher -
upload_cube_serial
- Uploads the build target to the User Interface chip using the STM32_Programmer_CLI with serial usb-c uploading. See Installation for instructions on installing the STM32_Programmer_CLI. -
upload_cube_swd
- Uploads the build target to the User Interface chip using the STM32_Programmer_CLI with st-link using SWD uploading. See Installation for instructions on installing the STM32_Programmer_CLI. -
docker
- Uses docker to compile, flash, and monitor the ui chip. By default it will compile the code. To change the functionality, pass a target of the Makefile into the parametermft
when being invoked.- Ex.
make docker mft=upload
- Ex.
make docker mft=monitor
- Ex.
-
monitor
- Opens a serial communication line with the management chip with a python script that allows for sending of commands. -
openocd
- Opens a openocd debugging instance. See Installation for instructions on installing openocd. -
dirs
- Makes all directories required for by the Makefile to compile and upload. -
docker-clean
- Removes dockere image that was generated when running docker target. -
clean
- Deletes the firmware/build/ui directory. -
info
- Displays the build path, include files, object files, dependencies and vpaths used by the compiler.
Source code
All source code for the User Interface can be found in firmware/ui, firmware/shared, and firmware/shared_inc. Adding C/C++ files in firmware/ui/src and firmware/ui/inc does not require any changes in the makefile.
Making a shared header between chips should be added into firmware/shared_inc.
The network chip is a MOQ client using quicr. The network chip communicates with the UI chip via UART serial communication.
We are leveraging the esp-idf framework.
Target Overview
-
all
- Runs thecompile
andupload
targets. -
compile
- Compiles the net code using the commandidf.py compile
-
upload
- Uploads the net code using openocd -
upload_py
- Uploads the build target to the Network chip using the our custom flasher tool with serial usb-c uploading. See Python Flasher -
upload_esptool
- Uploads the network chip code by first sending a command to the mgmt chip to put the board into net upload mode. Then usesesptool.py upload
-
docker
- Uses docker to compile, flash, and monitor the ui chip. By default it will compile the code. To change the functionality, pass a target of the Makefile into the parametermft
when being invoked.- Ex.
make docker mft=upload
- Ex.
make docker mft=monitor
- Ex.
-
monitor
- Opens a serial communication line with the management chip in debug mode using screen. -
py_monitor
- Opens a serial communication line with the management chip with a python script that allows for sending of commands. -
clean
- Deletes the firmware/net/build directory. -
fullclean
- Invokes idf.py fullclean. -
docker-clean
- Removes dockere image that was generated when running docker target.
Source code
All source code for the network chip can be found in firmware/net
, firmware/shared
, and firmware/shared_inc
.
The following tools are used for Management and User Interface.
- Make [required]
- ARM GNU Toolchain [required]
- Python3 [optional]
- ST-Flash [optional]
- STM32_Programmer_CLI [optional]
- OpenOCD [optional]
Make [required]
Make is used for compiling and uploading automation for each chip firmware.
Debian
sudo apt install make
Windows
-
Download make.exe from Source Forge
-
Save it to C:/bin or where ever you want it. Then add the location to the your path.
-
Open the start search, and type
env
. Select"Edit the system environment variables"
-
Click
"Environmental Variables..."
-
Under
"System Variables"
find the"Path"
entry, click"Edit..."
button. -
Click the
"New"
button and enterDRIVE:\path\to\make_location
- Note. Replace DRIVE with your appropriate drive letter, C, D, E... etc
-
You may need to restart your system after changing your system path.
MacOS
brew install make
ARM GNU Toolchain [required]
Debian
sudo apt install gcc-arm-none-eabi binutils-arm-none-eabi
Windows
- Download the appropriate ARM GNU Toolchain for your system https://developer.arm.com/downloads/-/gnu-rm
MacOS
brew install --cask gcc-arm-embedded
ST Flash
Debian
sudo apt install stlink-tools
Windows
Download the and install the archive and put the binaries on your path. https://github.com/stlink-org/stlink/releases
MacOS
brew install stm32flash
STM32 Programmer CLI [Optional]
The STM32 Programmer CLI comes packages with the STM32 Cube Programmer. You'll need to download and install The STM32 Cube Programmer and add the STM32_Programmer_CLI binary to your path.
https://www.st.com/en/development-tools/stm32cubeprog.html
Debian
-
Open your
.bashrc
file:sudo nano ~/.bashrc
-
Add the following line to the
.bashrc
fileexport PATH="$PATH:/path/to/stm_cube_programmer/bin"
-
NOTE - If you are getting an error saying that libusb needs permission to write usb, then you'll need to do an additional step.
- Navigate to
/path/to/stm_cube_programmer/Drivers/rules
- Edit 49-stlinkv2.rules
- Add the following to the bottom of the file
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", SYSFS{idVendor}=="3748", \ MODE="0666", \ GROUP="plugdev"
- Add the following to the bottom of the file
- Copy all of the rules to /etc/udev/rules.d/
cp /path/to/stm_cube_programmer/Drivers/rules/*.* /etc/udev/rules.d/
- Unplug then plug in your device and STMCubeProgrammerCLI should work.
- Navigate to
Windows
-
Open the start search, and type
env
. Select"Edit the system environment variables"
-
Click
"Environmental Variables..."
-
Under
"System Variables"
find the"Path"
entry, click"Edit..."
button. -
Click the
"New"
button and enterDRIVE:\path\to\stm_cube_programmer\bin
- Note. Replace DRIVE with your appropriate drive letter, C, D, E... etc
-
You may need to restart your system after changing your system path.
MacOS
- TODO
OpenOCD [optional]
Open On Chip Debugger, created by Dominic Rath, is a debugging software that can be used with micro-controllers to run debugging tools and stepping through code.
Debian
Run the following command:
sudo apt install openocd gdb-arm-none-eabi libnewlib-arm-none-eabi libstdc++-arm-none-eabi-newlib
If you don't have python3.8 installed, which is used for arm-none-eabi-gdb, then you'll need to install it
sudo add-apt-repository ppa:deadsnakes/ppa
apt update
sudo apt install python3.8
Windows
-
Download the appropriate zip for your system https://openocd.org/pages/getting-openocd.html
-
Open the start search, and type
env
. Select"Edit the system environment variables"
-
Click
"Environmental Variables..."
-
Under
"System Variables"
find the"Path"
entry, click"Edit..."
button. -
Click the
"New"
button and enterDRIVE:\path\to\openocd\bin
- Note. Replace DRIVE with your appropriate drive letter, C, D, E... etc
-
You may need to restart your system after changing your system path.
MacOS
Run the following commands in a terminal to install openocd
brew update
brew install open-ocd --HEAD
This project leverages the usage of the Arduino Library for the network chip.
The following tools are used for the Network.
Make [required]
Make is used for compiling and uploading automation for each chip firmware.
Debian
sudo apt install make
Windows
-
Download make.exe from Source Forge
-
Save it to OS bin directory or wherever you want it. Then add the location to the your path.
-
Open the start search, and type
env
. Select"Edit the system environment variables"
-
Click
"Environmental Variables..."
-
Under
"System Variables"
find the"Path"
entry, click"Edit..."
button. -
Click the
"New"
button and enterDRIVE:\path\to\make_location
- Note. Replace DRIVE with your appropriate drive letter, C, D, E... etc
-
You may need to restart your system after changing your system path.
MacOS
brew install make
esp-idf [required]
Debian
Windows
MacOS
Linux- You will need to be in the dialout group
- You will need to be in the docker group if you want to use the docker targets.
- At any point if you're including or using any additional STM32 HAL library files such as
stm32f4xx_hal_sd.h
then you must add the respective source filestm32f4xx_hal_sd.c
to C sources in the appropriate makefile. - New Assembly source files need to be added to the ASM sources line in the approriate makefile.
A firmware flashing tool designed to work with Hactar by collating STM32 and ESP32 flashing specifications.
- pyserial -
pip install pyserial
ex.
python3 flasher.py --port=/dev/ttyUSB0 --baud=115200 --chip="<chip>" -bin="./build/app.bin"
You can omit passing a port and the flasher will attempt to find a Hactar board by searching your active usb serial ports.
python3 flasher.py --baud=115200 --chip="ui" -bin="./build/ui.bin"
The serial monitor is a very simple serial monitor that allows a user to send commands to the mgmt chip as well as read serial logs. Located in firmware/tools
Requirements
- pyserial -
pip install pyserial
This monitor can be used by the following command:
python monitor.py \[port] \[baudrate]
ex.
python monitor.py /dev/ttyUSB0 115200
Display connector
- Required hardware
- 2.4 inch LCD Module from Waveshare
- Connector for display and Hactar board.
- From the display match the connector's pins with the associated pins on the connector.
- VCC -- VCC
- GND -- GND
- DIN -- DISP_DIN
- CLK -- DISP_CLK
- CS -- DISP_CS
- DC -- DISP_DC
- RST -- DISP_RST
- BL -- DISP_BL
Management Chip
- Prerequisites
- USB-C Cable
- Python3
- PySerial - download using
pip3 install pyserial
- PySerial - download using
- arm-none-eabi-g++
- make
- Build the mgmt code by navigating to
hactar/firmware/mgmt
and enteringmake compile
- Plug in a USB-C
- Press and hold the BOOT button, press and release the RESET button, finally release the BOOT button.
- Upload the mgmt code by entering
make upload
- After this you should see a couple of LED's light up
Main Chip
- Prerequisites
- A programmed
management chip
- USB-C Cable
- Python3
- PySerial - download using
pip3 install pyserial
- PySerial - download using
- arm-none-eabi-g++
- make
- A programmed
- Plug in the USB-C cable to the Hactar board.
- Build the ui code by navigating to the
hactar/firmware/ui
folder and enteringmake compile
- Upload the ui code by entering
make upload_py
- The python script "flasher.py" is called to upload to the main chip.
- NOTE - For some reason the Main STM32 chip doesn't like being put into bootloader mode this way. Fixing it is a WIP. You just need to keep trying... sorry.
- After finishing uploading the firmware to the main chip, the management chip will return to running mode.
Network Chip
- Prerequisites
- A programmed
management chip
- USB-C Cable
- esp-idf - must be on your path
- make
- A programmed
- Plug in the USB-C cable to the Hactar board.
- Build the net code by navigating to the
hactar/firmware/net
folder and enteringmake compile
- Upload the net code by entering
make upload_py
- The python script "flasher.py" is called to upload to the net chip
- NOTE - The size is quite large, takes about 4 minutes to upload.
- After finishing uploading the firmware to the net chip, the management chip will return to running mode.
Debug mode example
- Prerequisites
- Python3
- pyserial - download using
pip3 install pyserial
- pyserial - download using
- make
- USB-C Cable
- Python3
- Have your hactar board programmed and plugged in using a USB-C cable
- Navigate to either
hactar/firmware/ui
orhactar/firmware/net
- NOTE - Update your ports appropriately in the makefile
- Enter
make py_monitor
into your terminal - You should see a serial monitor open in your terminal requesting a command. Enter
debug
to put the hactar board into debugging mode.- See Management Commands for more commands that can be sent to the hactar board.
- The first and third LED from the left will turn blue indicating debug mode and your console will receive serial debug messages from the UI and Net chips.
- Enter
exit
to leave the monitor