AN2606: Using TRINAMIC’s IC Software API and Examples

1 Introduction

This application note describes the structure of the ADI TRINAMIC software application programming interface (API) and how it can be used to simplify and speed up firmware development based on hardware with TRINAMIC motion control chips. The software API is part of the TMC-EvalSystem ^[2] . The TMC-EvalSystem can be used together with the TMC evaluation boards ^[1] to directly start developing.

This application note explains which compiler and tools can be used to compile the TMC-EvalSystem project and how to upload the firmware to a module using a third party programmer or the standard bootloader with the TMCL-IDE.

1.1 Software API Project Structure

The API is a portable C library for working with Trinamic ICs in embedded projects. It is processor independent and self-contained. There are no external dependencies. Hallo ist das ein Überfall? For example, the API is used for ADI TRINAMIC’s modular evaluation system boards called LandungbrückeV3 (GigaDevice GD32F425VG processor) ^[5] and Landungbrücke (Freescale MK20 processor).

The API is structured as shown in Figure 1:

The folder tmc/ic contains a folder for each ADI TRINAMIC chip, example, tmc/ic/TMC5130. Each folders contains a header file with the chip’s register address list, register - field definitions and constants (example, TMC5130_HW_Abstraction.h). Another .h and .c file (example, TMC5130.h/.c) provides functions for the specific chip. Low level functions are necessary for SPI read and write access. These low level functions (example, tmc5130_writeRegister, tmc5130_readRegister) simplify the process of interacting with the registers. The user can quickly and effortlessly read information from each register or modify their values with just a few lines of code. These functions greatly simplify the process of working with IC registers, allowing developers to harness the full potential of ADI Trinamic’s ICs and save valuable time.

As a starting point for the development of every IC folder has a subfolder with example codes. These examples showcase specific functions of the IC. These examples can be implemented in a project to get a starting point.

For futher details, consult the README of the specific IC.

Chapter 1.2 shows the use of the API in a firmware project on the example of the ADI TRINAMIC evaluation board firmware project for Landungbrücke.

1.2 Evaluation Board Project Structure

The evaluation board project demonstrates the use of the TMC-API and can be used as a starting point for own firmware development. It should be an example to simplify and speed up firmware development based on hardware with TRINAMIC motion control ICs. The structure of the evaluation board project is shown in Figure 2:

The evaluation board project is a makefile project and supports two processor types: a GigaDevice GD32F425VG (cortex M4 processor used in the LandungbrueckeV3) ^[5] and a Freescale MK20 (cortex M4 processor used in the Landungbruecke). The processor can be selected according to a build-command for the makefile. The complete firmware project is provided as is available for free use and adaption ^[2] . The project uses the Eclipse IDE for C/C++ developers and can be extended for further processor types and evaluation boards.

On top of the CPU-specific firmware part, a hardware abstraction layer is implemented, to abstract the access to digital IO, the analog-to-digital converter (ADC) measurement, serial port interface (SPI), communication, pulse-width modulation (PWM), and evaluation board detection from the CPU-specific firmware part. The evaluation board firmware detects connected evaluation boards automatically and loads a board-specific firmware part dynamically corresponding to the actual connected evaluation board. This firmware part uses the TMC-API for the header file and the *.h/*.c file for the specific functionality of the actual used ADI TRINAMIC motion control IC. Using the hardware abstraction layer, each evaluation board has access to a wide range of CPU functions in a CPU independent way.

2 Requirements and Installation Guide

This section describes the list of tools needed to compile the firmware project and upload it to the Landungsbrücke. For the installation and configuration, a step-by-step guide with screenshots is presented.

2.1 Tools

These are the software packages necessary to use the TMC-API in the project:

Eclipse

An open-source integrated development environment (IDE).

GNU ARM

Embedded Toolchain Pre-built GNU toolchain for ARM and Cortex-M processors.

TMCL-IDE

The visual software to control and update ADI TRINAMIC modules and evaluation boards.

2.1.1 Eclipse

Eclipse is used to organize, program, and compile software projects. Other IDEs can be used instead, but the TMC-API project was developed with it and the Eclipse project files are provided along with the code.

Download the latest version of Eclipse from https://Eclipse.org/downloads/, choose the package “Eclipse IDE for Embedded C/C++ Developers” as shown on Figure 3, and follow the installation wizard.

For older versions of Eclipse or other installation methods, it is necessary to download the “Eclipse MCU” plug-in from https://marketplace.Eclipse.org/content/Eclipse-embedded-cc.

2.1.2 GNU ARM Embedded Toolchain

The GNU ARM Embedded GCC can be use to compile the firmware. Download the most recent release from https://developer.arm.com/downloads/-/gnu-rm. Follow the installation wizard to set up the toolchain in the system. Select “Add path to environment variable”, as shown in Figure 4.

2.1.3 TMCL-IDE

The TMCL-IDE software tool is developed by ADI TRINAMIC and offers many tools and wizards to control various ADI TRINAMIC modules and evaluation board products. The TMCL-IDE can be use to update the firmware of a ADI TRINAMIC evaluation board. Download the latest TMCL-IDE release from https://www. analog.com/en/resources/evaluation-hardware-and-software/motor-motion-control-software/tmcl-ide. html#latest and install it in the system.

To update the firmware of a module without the bootloader feature (example, self-designed boards), it is required to have a programmer device. The following are the two common options for some of the most popular embedded processor families: (more information about debugging in section 3.)

• Arm MBED DAPLink: open-source software project for programming and debugging application running on Arm Cortex MCUs https://github.com/ARMmbed/DAPLink
• Segger J-Link: USB-powered JTAG debug probe supporting a large number of CPU cores. https://www.segger.com/products/debug-probes/j-link/

Note: The TMCL-IDE is also available for Linux. It is nessesary to add the access rights for the USB to the USER by:

sudo usermod −aG $❨stat −c "%G" /dev/ttyACM0❩ $USER

For some distribution, it is required to install some libraries. Example, for openSUSE “ilbgthread-2_0-0” or for Debian:

sudo apt−get install libxcb−icccm4, libxcb−image0, libxcb−keysyms1, libxcb−render−util0

2.2 How to Create and Update a New Firmware Image

This section explains the steps to follow to set up the programming environment to use the ADI TRINAMIC TMC-API project. Afterwards, create his own firmware image and update it to an ADI TRINAMIC evaluation board.

• Download TMC-API [3] and TMC-EvalSystem [4] projects
• Put the TMC-API content in TMC-EvalSystem
• Import TMC-API and TMC-EvalSystem Eclipse projects
• Build the firmware
• Update your evaluation board

2.2.1 Download TMC-API and TMC-EvalSystem from GitHub / AnalogDevicesInc

Download the ADI TRINAMIC TMC-API ^[3] and TMC-EvalSystem ^[4] source code projects from the AnalogDevicesInc GitHub website for free use and adaption (MIT license). Extract the *.zip files “TMC-API-xxxxxx.zip” and “TMC-EvalSystem-xxxxxx.zip”. Select the “TMC-EvalSystem-xxxxxx” folder in the workspace (example, C:// User/<Username>/workspace). Select the content of the “TMC-API-xxxxxx” folder and place it in the “TMC-API” folder in the TMC-EvalSystem.

2.2.2 Import TMC-API and TMC-Evalsystem Eclipse projects

Open Eclipse, choose a workspace path, and click “Workbench” to close the welcome screen. Next, click “File - Import” and choose “Existing Projects into Workspace” under “General”, as shown in Figure 5. Then, click “Next”.

Click “Browse" and choose the path of the workspace, and then add the TMC-EvalSystem project. Select “TMC-EvalSystem”. Proceed with “Finish”, as shown in Figure 6.

After importing both projects containing the source code into Eclipse, to start, choose a file and start to edit the file. For example, on the left panel, open the TMC-EvalSystem project and double click main.c to open the file. The source code shows on the central panel, as shown in Figure 7.

2.2.3 Build Firmware

At this point, the firmware image is ready to be built. Click the project “TMC-EvalSystem” to select it. To start the compilation, click “Build Targets” on the top right panel. It can also be found on the file tree view under the project name shown in Figure 7.

Select the appropriate target for the board. For a LandungsbrückeV3 evaluation board, double-click “LandungsbrückeV3_BL” (as highlighted in the image). If the board is a Landungsbrücke evaluation board, double-click “Landungsbrücke_BL”. In the console (bottom panel), the compiler output shows a “Build finished” message when the process finishes successfully.

Targets ending with “NOBL” are for boards without a bootloader. The created firmware images must be flashed with a programmer instead of using the TMCL-IDE firmware update tool. More in section 3.

2.2.4 Update a Module

Open the TMCL-IDE software. Power and connect the module. The module appears on the left panel. Click “Tools - Firmware Update” or on its icon on the top-right toolbar (an arrow pointing down, highlighted in Figure 8). Check that the selected module is correct and click “Browse” to find the firmware image.

Move to the Eclipse workspace path and open the build folder of the module inside the TMC-EvalSystem project. There is a .hex file, and the name indicates the module and firmware version.

The Figure 8 shows an example with a Landungsbrücke evaluation board. Here, the selected module matches the one shown on the left panel. The “TMC-EvalSystem” path appears in the smaller window. Here, select the “Landunsbruecke_x.xx_BL.hex” file from the “_build_Landungsbrücke” folder.

If the firmware image is compatible with the module, the “Update” is no longer grayed out. Click “Update”, as shown in Figure 9.

For a non-bootloader firmware image, connect the programmer device to the PC and module. More information in the next section.

Afterwards, reboot module and have fun with the evaluation board or own designed module.

3 Flashing and Debugging the Code

The debugging is demonstrated with a SEGGER J-Link Plus and some DAPLink debuggers. It can also be performed by other devices

3.1 Flashing a NOBL Version with a J-Link

Attention: Read section 3 carefully before starting!

This subsection explains how to flash a version with no bootloader (_NOBL) on an evaluation board without using the IDE. The following steps are required to flash a _NOBL version:

• Install the J-Link software. Download it ^[6] . Select “install legacy USB driver”.
• Open Eclipse and prepare it like shown in section 2.2.2
• Build the firmware as shown in section 2.2.3. But choose the _NOBL version instead.
• Connect the J-Link using USB to the PC and with Landungsbrücke 3.1.1.
• Use J-Flash Lite to flash the firmware 3.1.2.

3.1.1 Landungsbrücke to J-Link Connection

There are several ways to connect the Landungsbrücke to the J-Link.

First option: Download Programming-Adapter.zip file. Programming Adapter For the PCB building please upload the files out of the ../FAP folder to a PCB - manufacturer and order the PCB. For the assembly there is a Bill Of Material in the ../BOM folder.

First option: download the "Programming-Adapter.zip file" (Programming Adapter). To build the PCB, upload the files from the ../FAP folder to a PCB manufacturer and order the PCB. For the assembly, there is a bill of material in the ../BOM folder.

Second option: Solder to the backside of the Landungsbrücke cables as shown in Figure 11. The power, DIO, and CLK cables are required. The reset pin is only required in case of flashing problems.

Third option: For Landungsbrücke_V3, there are holes in the PCB. Plug jumper wires in these as shown in Figure 12. This is the simplest solution. The “Reset” pin is also on the front. For Landungsbrücke V1 and V2 or small, the reset pin is on the MCU side of the “C204” [5].

3.1.2 Flash the Firmware with J-Link

Attention: Read section 3 carefully before starting!

Open ‘J-Flash Lite”. To start, enter the processor ID. They are:

Landungsbrücke_V1 = MK20DN512xxx10
Landungsbrücke_small = MK20DX256xxx10
Landungsbrücke_V3 = GD32F425VG

Browse in the J-Flash Lite for the folder: “..//TMC-EvalSystem/_build_LandungsbrückeVx” and select “LandungsbrückeVx ... NOBL.hex”. Then click “Program Device”.

3.2 Debugging with the J-Link

Attention: Read section 3 carefully before starting!

This section gives a brief overview on how to debug TMC-EVAL system in case there is a need to know how the code is structured or to test certain scenarios with the evaluation system before they are implemented in the field.

Before starting with the debugging, prepare Eclipse as shown in section 2 and install the J-Link software packet ^[6] . It is maybe required to select “install legacy USB driver”. Also, build the firmware as shown in 2.2.3 but with a _NOBL version.

3.2.1 Prepare the Eclipse for the Debugging

Set the configuration for the debugger in Eclipse, as follows:

There are two options to start the GDB server either: manually or automatically. In both cases, set the “Device Name” as explained in 3.1.2.

Attention: Read section 3 carefully before clicking on “Debug:” !

3.3 Flashing a NOBL Version with a DAPLink

Attention: Read section 3 carefully before starting!

This section describes an alternative way to program and debug the TMC-Eval-System. This way is recommended for more experienced users looking for a cost-effective, open-source alternative.

The DAPLink standard is open, and there are numerous options to chose from. The debugging is explained for a “RAKDAP1” by RAK and a “‘MAX32625PICO” by Analog Device. The “RAKDAP1” is open source hardware and therefore available under many names from other vendors. The “MAX32625PICO” board is a rapid development platform designed to help engineers quickly implement designs ^[8] .

3.3.1 Installing PyOCD

There are two options available as software interface: PyOCD or openOCD. For this demonstration, pyOCD is used.

1. Step: Install Python as shown in section 4.1.2.
2. Step: Open a Microsoft CMD window and install pyOCD with the following comman d:
   

   pip install pyocd

3. Step: Get the list of all MCUs available for pyOCD by:
   

   pyocd pack update

4. Step: Seach in the pack if the MCU of the Landungsbrücke version is available ( 3.1.2) by:
   

   pyocd pack find <MCU−Name>

5. Step: Install the MCU pack for Landungsbrücke version by:
   

   pyocd pack install <MCU−Name>

3.3.2 Connect the Landungsbrücke to a DAPLink

Generally, the DAPLink is connected in one of the ways described in section 3.1.1. Option 1 has the advantage that the signal quality is generally better because of the resistors and capacitor. Option 2 and 3 also work fine. Another advantage of this set up is that no USB connection is needed to the Landungsbrücke because the DAPLink debugger can supply the necessary voltage.

The Figure 16 and Figure 17 show the wiring for both devices. Option 2 and 3 are wired up in the same way. The MAX32625PICO requires a 1.27mm, 10-pin, 2x5 converting adapter or cable to cut open, as self-made adapter, because the header is too small for jumper wires.

3.3.3 Flash the Firmware with a DAPLink

Attention: Read section 3 carefully before starting!

1. Go in the “Windows System File Explorer” to the workspace and into ../TMC-EvalSystem/_build_Landungsbruecke_Vx.
2. Click on the URL line of the “File Explorer” and replace its content with “CMD”.
3. CMD opens with the folder as directory. Use the following code to flash the firmware. Copy and paste to CMD:
   

   pyocd load −−target  −−frequency 4000000 LandungsbrueckeV$_v$$$$_NOBL.elf

4. Replace <MCU-Name> with the name of the Landungsbrücke MCU. See section 3.1.2.
5. There is also a need to exchange the filename. The easiest option is to remove the hole filename and type a “L” and then use the “–>” or “TAB” button on the keyboard. CMD then autofills the correct filename. Check the file ending. “.elf”, “.bin”, and “.hex” are fine. If the ending is missing, fill it.
6. Press return.

Optional: To erase the firmware, use the following code:

pyocd erase −−target  −−frequency 4000000 −−mass

3.4 Debug with a DAPLink

The debugging follows the same process as described in section 3.2.1.

1. Get Eclipse ready as described in section 2.
2. Build the firmware.
3. Open “Debug Configurations... ” as shown in Figure 13.
4. Select “GDB PyOCD Debugging” and fill in the fields as shown in Figure 14.
5. Go to the “Debugger” tab and fill in the fields shown in Figure 15. The executable path is: “C:/Users/<Username>/A
6. Enable the “Overwrite Target” and set it to the MCM name of the Landungsbrücke ( 3.1.2).
7. Select the debugger under “Debug probe”.
8. Read section 3 carefully! Select “Apply” and “Debug”.

Alternatively, the following code can be used to start the GDB Server in CMD:

pyocd gdbserver −−target <MUC−Name> −−frequency 4000000 −−elf LandungsbrueckeV$_v$_NOBL. ,→ elf

3.5 Flashing and Debugging on Linux

Attention: Read section 3 carefully before starting!

If a Linux distribution is used instead of Microsoft Windows, the general process is the same like for Windows. Mac OS is also a UNIX distribution and can therefore be also used. But the process is not tested for Mac OS. It is expected that the Linux user is familiar with the command shell. For trying out Linux, a Linux MINT distribution is recommended strongly, because it has most drivers and libraries. Therefore, beginning is easier.

The following process for flashing and debugging is tested with Debian, Ubuntu, Mint, openSUSE, Manjaro, and Fedora-Workstation. It works over a brought range of distribution. Every one of them has its specifics. Therefore, the user is expected to know or find the specific information for distribution. To make the process beginner friendly, Linux MINT 22 Cinnamon is used in this explanation.

This subsection explains how to flash a version with no bootloader (_NOBL) on an evaluation board without using the TMCL-IDE. The following steps are nessesary to flash a _NOBL version:

1. Open Eclipse and prepare it as shown in section 2.2.2.
2. Adjust the Eclipse project for Linux 3.5.1.
3. Install the libraries for the compiler 3.5.2.
4. Build the firmware as shown in section 2.2.3. But choose the _NOBL version instead. Alternatively, the terminal can be used. 3.5.4.
5. Connect the DAP-Link using USB to the PC 3.3.
6. Use the command window to flash the firmware 3.1.2.
7. Alternatively, debug with terminal and Eclipse 3.5.5.

3.5.1 Eclipse Settings for Linux

The Evalsystem project is developed for Microsoft Windows and therefore uses "cs-make". Under Linux, use "make" instead. Change the Makefile target, as shown in Figure 18.

3.5.2 Install Libraries Under Linux

Like under Microsoft Windows, Linux also needs libraries. The necessary libraries are arm-none-eabi gcc, newlib, and gdb, as well as the “make” itself.

Go to the start menu, type “terminal”, and press enter. Then, execute the following code:

sudo apt−get update
sudo apt−get installmake
sudo apt−get install gcc−arm−none−eabi

Type the password and confirm to install the libraries.

3.5.3 Build Firmware in Terminal

Alternatively, the following commands can be executed from the workspace folder, which contains the EvalSystem. Start the terminal in this folder and run the commands:

LandungsbrückeV1

• make -s all LINK=BL DEVICE=Landungsbruecke
• make -s clean LINK=BL DEVICE=Landungsbruecke
• make -s all LINK=NOBL DEVICE=Landungsbruecke
• make -s clean LINK=NOBL DEVICE=Landungsbruecke

LandungsbrückeSmall

• make -s all LINK=BL DEVICE=LandungsbrueckeSmall
• make -s clean LINK=BL DEVICE=LandungsbrueckeSmall
• make -s all LINK=NOBL DEVICE=LandungsbrueckeSmall
• make -s clean LINK=NOBL DEVICE=LandungsbrueckeSmall

LandungsbrückeV3

• make -s all LINK=BL DEVICE=LandungsbrueckeV3
• make -s clean LINK=BL DEVICE=LandungsbrueckeV3
• make -s all LINK=NOBL DEVICE=LandungsbrueckeV3
• make -s clean LINK=NOBL DEVICE=LandungsbrueckeV3

3.5.4 Flash the Firmware in Terminal

Install pyOCD by running the following commands:

test sudo

Continue the installation as described in section 3.3.

3.5.5 Debug the firmware in Terminal and with Eclipse

The debugging is for Linux is similar to that described in section 3.2.1.

Install a configured version of Eclipse ( 3.5.1) and all libraries for flashing ( 3.5.2) and for debugging. A GNU Debugger (in short GDB) is need for the debugging. The GDB itself is not enough. Therefore, it is nessesary to install a GDB with more capabilities. There are two options: on the one hand the “arm-noneeabi-gdb” and on the other hand the “GDB-multiarch”. Both are able to debug the EvalSystem. Because of the difficult installation of the “arm-none-eabi-gdb”, the “GDB-multiarch” is used. Install “arm-none-eabigdb” from a local package and install everything by your self.

Run the following command to install “GDB-multiarch”:

sudo apt-get install gdb-multiarch

Follow these steps to set up the debug configuration:

1. Open “Debug Configurations... ” as shown in Figure 13.
2. Select “GDB PyOCD Debugging” and fill in the fields as shown in Figure 14.
3. Go to the “Debugger” tab and fill in the fields shown in Figure 20. The executable path is: “/usr/bin/gdbmultiarch”
4. Read section 3 carefully! Select “Apply” and “Debug”.

For debugging, follow these steps:

1. Build the firmware.
2. Start the pyOCD gdbserver (3.4)
3. Read section 3 carefully! Select “Debug” and choose the configuration (Figure 13).

4 PyTrinamic

PyTrinamic is an alternative tool to the TMC-IDE. “PyTrinamic” can be used as a Python library with example code ^[7] For each IC, there are some demo scripts. They can be used as a starting point for own scripts.

4.1 How to Start Using PyTrinamic

This section makes a brief introduction on PyTrinamic and how to install it.

4.1.1 Downloading PyTrinamic

Download the PyTrinamic example codes at the ADI Trinamic GitHub page ^[7] . Extract the *.zip files and place it in the workspace.

4.1.2 Python

To run the Python scripts, an interpreter is required. Download it here: https://www.python.org/downloads/

Follow the installation wizard and select Add to [. . .] PATH as shown in Figure 21.

4.1.3 PyCharm

PyCharm is an IDE to organize, program, and compile Python code. Other IDEs can be used instead, but the PyTrinamic project was developed with it. PyCharm is available in two versions. The community version is sufficient for PyTrirnamic. It can also be used with the professional version, .

Download the latest version of PyCharm from https://www.jetbrains.com/pycharm/download/ and follow the installation wizard.

Import the PyTrinamic - Project by clicking “open” in PyCharm. If a project is already added, find Open in the Menu at the top left.

To run the demo code, it is nessesary to click “Trust Project” (Figure 22).

If asked, select Python interpreter 3.10.xx as shown in Figure 23. Otherwise, add it manually (see Figure 23).

Click “Python 3.10” and select “Interpreter Settings... ” as shown in Figure 24 It is maybe needed to select at the left setup.py.

Optional: If not done before, add the interpreter manually: “Add interpreter” -> “Add local interpreter” -> “System Interpreter”-> select “Python310”.

Optional: For some scripts, it is required to install the “matplotlib”. For adding, click “+” and search for “matplotlib” and install it Figure 25

Check if the “pytrinamic” package is added. If not, add it in the same way.

For alternative ways of installing, check if all necessary packages are installed.

4.2 Run Example Script

The following are the steps to run the example scripts for the TMC5130-EVAL.

• On the left, select the “rotate_demo.py”.
• Ensure the “Current file” is selected.
• Click the green arrow at the top right.

See Figure 26.

In the bottom, a command window appears. It contains all prints of the code, like for example, the actual speed and velocity.

5 References

[1] TRINAMIC, “Landungsbrücke Eval System overview” https://www.analog.com/resources/evaluation-hardware-and-software/motor-motion-control-software/landungsbrucke-eval-system.html

[2] GitHub AnalogDevicesInc, “TMC-EvalSystem firmware for Landungsbrücke” https://github.com/analogdevicesinc/TMC-EvalSystem/releases

[3] TRINAMIC, “TMC-API Eclipse project” https://github.com/analogdevicesinc/TMC-API

[4] TRINAMIC, “TMC-EvalSystem Eclipse project” https://github.com/analogdevicesinc/TMC-EvalSystem

[5] TRINAMIC, ”LandungsbrückeV3 evaluation board” https://www.analog.com/resources/evaluation-hardware-and-software/evaluation-boards-kits/Landungsbruecke.html

[6] SEGGER, “J-Link GDB - Server" https://www.segger.com/products/debug-probes/j-link/tools/j-link-gdb-server/about-j-link-gdb-server/

[7] GitHub AnalogDevicesInc, “PyTrinamic download” https://github.com/analogdevicesinc/PyTrinamic

[8] Analog Devices, “MAX32625PICO product page” https://www.analog.com/resources/evaluation-hardware-and-software/evaluation-boards-kits/max32625pico.html

6 Revision History