This repository gives an example of how to set up micro-ROS on any STM32 microcontroller. For this repository an STM32F429ZI was chosen but you are free to choose another one.
You can also find the instructions in video form here: https://youtu.be/xbWaHARjSmk
If you follow all steps in the tutorial you should have an STM32 microcontroller with a micro-ROS publisher that transmits messages via UART to your PC running ROS 2. Here you can receive the messages via ros2 topic echo.
In the following the required steps to achieve the goal are presented in detail.
It will show how to do this for a microcontroller that is not listed as a device directly supported by micro-ROS.
If you find that you have problems check out the Troubleshooting section below.
1.) Create a new CubeMx project for your micro controller
2.) In System Core -> RCC -> High Speed Clock (HSE) select Crystal/Ceramic Resonator
3.) In System Core -> SYS -> Timebase Source select TIM1
4.) In Middleware -> FREERTOS -> Interface select CMSIS_V2
4.1.) In Middleware -> FREERTOS -> Configuration -> Task and Queues double click the defaultTask and set a stack size of 3000. It has to be greater than 10.000 byte (3000 words * 4 byte = 12.000 byte).
5.) In Connectivity choose the UART / USART that you want to use.
5.1.) In the Uart configuration, go to DMA Settings. Click on the Add button. Click on the Select dropdown and choose both Rx and Tx.
5.2.) Click on the Rx DMA you've just created and for Mode choose Circular.
5.3.) For the priority of the DMA choose Very high for both Rx and Tx.
5.4.) Go to NVIC Settings of the UART and activate the UARTx global interrupt.
6.) Set up the Clock Configuration for your micro controller
7.) In Project Manager select a folder where to generate your code
7.1.) In Toolchain / IDE select Makefile
7.2.) Optional: In Project Manager -> Code Generator select Generate peripheral intitialization as a pair of '.c/.h' files per peripheral
8.) Click on Generate Code
9.) In the root folder of the code you've just generated, clone the following repository (into a subfolder, don't change its name).:
git clone https://github.com/micro-ROS/micro_ros_stm32cubemx_utils.git10.) Make sure you have the right branch for your ROS version checked out
11.) In the Makefile that was generated by CubeMx put the following code snippet after the part where it says build the application:
#######################################
# micro-ROS addons
#######################################
LDFLAGS += micro_ros_stm32cubemx_utils/microros_static_library/libmicroros/libmicroros.a
C_INCLUDES += -Imicro_ros_stm32cubemx_utils/microros_static_library/libmicroros/microros_include
# Add micro-ROS utils
C_SOURCES += micro_ros_stm32cubemx_utils/extra_sources/custom_memory_manager.c
C_SOURCES += micro_ros_stm32cubemx_utils/extra_sources/microros_allocators.c
C_SOURCES += micro_ros_stm32cubemx_utils/extra_sources/microros_time.c
# Set here the custom transport implementation
C_SOURCES += micro_ros_stm32cubemx_utils/extra_sources/microros_transports/dma_transport.c
print_cflags:
@echo $(CFLAGS)11.) Pull and run the following docker to generate the micro-ros lib. Make sure you use the right ROS version when you pull / run the docker. This should be executed in the root folder of your project.
docker pull microros/micro_ros_static_library_builder:galactic
docker run -it --rm -v $(pwd):/project --env MICROROS_LIBRARY_FOLDER=micro_ros_stm32cubemx_utils/microros_static_library microros/micro_ros_static_library_builder:galactic12.) If it asks for the CFLAGS, if you can see some, continue. They might look like this:
Found CFLAGS:
-------------
-mcpu=cortex-m4 -mthumb -mfpu=fpv4-sp-d16 -mfloat-abi=hard -DUSE_HAL_DRIVER -DSTM32F429xx -ICore/Inc -IDrivers/STM32F4xx_HAL_Driver/Inc -IDrivers/STM32F4xx_HAL_Driver/Inc/Legacy -IMiddlewares/Third_Party/FreeRTOS/Source/include -IMiddlewares/Third_Party/FreeRTOS/Source/CMSIS_RTOS -IMiddlewares/Third_Party/FreeRTOS/Source/portable/GCC/ARM_CM4F -IDrivers/CMSIS/Device/ST/STM32F4xx/Include -IDrivers/CMSIS/Include -IDrivers/CMSIS/Include -Imicro_ros_stm32cubemx_utils/microros_static_library/libmicroros/microros_include -Og -Wall -fdata-sections -ffunction-sections -g -gdwarf-2 -MMD -MP -MFprint_cflags
-------------
If instead the CFLAGS are empty there was likely a mistake. If you get an error about a missing separator in the Makefile, check the line in the Makefile. For me there were 2 similar includes. I deleted one of them.
13.) If you get an error like this during building:
'rcutils' exports library 'dl' which couldn't be found
That's ok and can be ignored.
14.) Go into Core/main.cpp and adjust it so that it's similar to the sample_main.cpp you can find in the micro_ros_stm32cubemx_utils repository we found earlier. The most interesting parts are the following:
#include <rcl/rcl.h>
#include <rcl/error_handling.h>
#include <rclc/rclc.h>
#include <rclc/executor.h>
#include <uxr/client/transport.h>
#include <rmw_microxrcedds_c/config.h>
#include <rmw_microros/rmw_microros.h>
#include <std_msgs/msg/int32.h>bool cubemx_transport_open(struct uxrCustomTransport * transport);
bool cubemx_transport_close(struct uxrCustomTransport * transport);
size_t cubemx_transport_write(struct uxrCustomTransport* transport, const uint8_t * buf, size_t len, uint8_t * err);
size_t cubemx_transport_read(struct uxrCustomTransport* transport, uint8_t* buf, size_t len, int timeout, uint8_t* err);
void * microros_allocate(size_t size, void * state);
void microros_deallocate(void * pointer, void * state);
void * microros_reallocate(void * pointer, size_t size, void * state);
void * microros_zero_allocate(size_t number_of_elements, size_t size_of_element, void * state);void StartDefaultTask(void *argument)
{
/* USER CODE BEGIN StartDefaultTask */
/* Infinite loop */
// micro-ROS configuration
rmw_uros_set_custom_transport(
true,
(void *) &huart2,
cubemx_transport_open,
cubemx_transport_close,
cubemx_transport_write,
cubemx_transport_read);
rcl_allocator_t freeRTOS_allocator = rcutils_get_zero_initialized_allocator();
freeRTOS_allocator.allocate = microros_allocate;
freeRTOS_allocator.deallocate = microros_deallocate;
freeRTOS_allocator.reallocate = microros_reallocate;
freeRTOS_allocator.zero_allocate = microros_zero_allocate;
if (!rcutils_set_default_allocator(&freeRTOS_allocator)) {
printf("Error on default allocators (line %d)\n", __LINE__);
}
// micro-ROS app
rcl_publisher_t publisher;
std_msgs__msg__Int32 msg;
rclc_support_t support;
rcl_allocator_t allocator;
rcl_node_t node;
allocator = rcl_get_default_allocator();
//create init_options
rclc_support_init(&support, 0, NULL, &allocator);
// create node
rclc_node_init_default(&node, "cubemx_node", "", &support);
// create publisher
rclc_publisher_init_default(
&publisher,
&node,
ROSIDL_GET_MSG_TYPE_SUPPORT(std_msgs, msg, Int32),
"cubemx_publisher");
msg.data = 0;
for(;;)
{
rcl_ret_t ret = rcl_publish(&publisher, &msg, NULL);
if (ret != RCL_RET_OK)
{
printf("Error publishing (line %d)\n", __LINE__);
}
msg.data++;
osDelay(10);
}
/* USER CODE END StartDefaultTask */
}15.) Open the project in your favorite IDE. In general you should now be able to build and debug your program. To built I used the arm-none-eabi-toolchain. To flash and debug I used openocd. If you can not build check step 15.1.
15.1.) It might be that you can not build yet because of missing syscalls. In that case you might get errors like undefined reference to _kill or undefined reference to _getpid. In that case add a syscalls.c file to your project and also add it to the Makefile so that it will be compiled. You can find an example syscalls.c at the end of this page.
19.) Now you need a micro-ROS agent. It's responsible to create the communication between your embedded controller and the rest of your ROS 2 software. Create a different folder that will be used as a ROS 2 workspace.
20.) Clone the micro_ros_setup repository and build it by executing the following steps from the root of your workspace folder:
source /opt/ros/$ROS_DISTRO/setup.bash
git clone -b $ROS_DISTRO https://github.com/micro-ROS/micro_ros_setup.git src/micro_ros_setup
rosdep update && rosdep install --from-path src --ignore-src -y
colcon build
source install/local_setup.bash21.) Build the agent packages
ros2 run micro_ros_setup create_agent_ws.sh
ros2 run micro_ros_setup build_agent.sh
source install/local_setup.shI got a warning about stderr output when running build_agent.sh (at the end of the build process) but I ignored that. I also had a problem were build_agent.sh complained about being unable to find a package (Package 'micro_ros_agent' specified with --packages-up-to was not found). This was because I didn't follow the steps to build the workspace first correctly (step 20).
22.) Start the micro-ros-agent. For example:
ros2 run micro_ros_agent micro_ros_agent serial -b 115200 --dev /dev/ttyACM0serial: for UART use, other options available -b: baudrate --dev: the device to use
To get help with the usage:
ros2 run micro_ros_agent micro_ros_agent --help23.) In the agent you should see something like this:
[1641665035.090947] info | TermiosAgentLinux.cpp | init | running... | fd: 3
[1641665035.130109] info | Root.cpp | create_client | create | client_key: 0x041835D4, session_id: 0x81
[1641665035.130212] info | SessionManager.hpp | establish_session | session established | client_key: 0x041835D4, address: 0
[1641665035.156038] info | ProxyClient.cpp | create_participant | participant created | client_key: 0x041835D4, participant_id: 0x000(1)
[1641665035.171020] info | ProxyClient.cpp | create_topic | topic created | client_key: 0x041835D4, topic_id: 0x000(2), participant_id: 0x000(1)
[1641665035.181034] info | ProxyClient.cpp | create_publisher | publisher created | client_key: 0x041835D4, publisher_id: 0x000(3), participant_id: 0x000(1)
[1641665035.191347] info | ProxyClient.cpp | create_datawriter | datawriter created | client_key: 0x041835D4, datawriter_id: 0x000(5), publisher_id: 0x000(3)
[1641665052.957930] info | SessionManager.hpp | establish_session | session re-established | client_key: 0x041835D4, address: 0
This is some kind of handshake between the agent and the embedded system. You might have to restart your MCU, the agent should be started first it seems.
If you see something like this instead:
[1641665033.757172] info | TermiosAgentLinux.cpp | init | Serial port not found. | device: /dev/ttyACM0, error 2, waiting for connection...
[1641665034.757430] info | TermiosAgentLinux.cpp | init | Serial port not found. | device: /dev/ttyACM0, error 2, waiting for connection...
You have likely selected the wrong device or your MCU is not connected.
23.) You should now be able to see the messages published by the MCU on ROS2:
ros2 topic echo /cubemx_publisher
The data would look like this:
---
data: 2399
---
data: 2400
---
data: 2401
---
data: 2402
---
data: 2403
---
data: 2404
---
When stepping through the code the programs hangs at rclc_support_init.
Be sure that the UART you use when calling rmw_uros_set_custom_transport is the one that you set up for ROS (e.g. with the right DMA settings).
Also be aware that the call to this function can take some time (~10 seconds). When running the micro-ROS agent it usually is faster though.
The publishing doesn't work. I go into the error case in the infinite loop of the main task:
rcl_ret_t ret = rcl_publish(&publisher, &msg, NULL);
if (ret != RCL_RET_OK)
{
printf("Error publishing (line %d)\n", __LINE__); // <-------------------- this is entered
}
In my case I can see some prints on the UART before entering the while loop. There is a lot of random bytes but sometimes I can see XRCE.
You need a running micro-ROS agent. See steps 19.) and following. If you have an agent running but it still doesn't work, look at problem / solution 6.
When trying to flash the board, I get an openocd bug saying something with "free"
Unplug MCU and replug it (power).
When I run the agent and MCU the agent says
fynn@sphalerite:~/main/dev/tests/micro-ros/agent_ws$ ros2 run micro_ros_agent micro_ros_agent serial -b 115200 --dev /dev/ttyACM0
[1643036775.906617] info | TermiosAgentLinux.cpp | init | running... | fd: 3
[1643036775.906762] info | Root.cpp | set_verbose_level | logger setup | verbose_level: 4
but nothing else happens and I can't receive my data.
Check that your MCU doesn't crash anywhere (e.g. in the syscalls).
I get an error saying that _getpid and _kill are not defined.
You need to define a syscalls.c file and add these function with their functionality.
You can find an example of such a file at the end of this page.
When I run the agent and the MCU, the agent says
[1641665035.090947] info | TermiosAgentLinux.cpp | init | running... | fd: 3
[1641665035.130109] info | Root.cpp | create_client | create | client_key: 0x041835D4, session_id: 0x81
[1641665035.130212] info | SessionManager.hpp | establish_session | session established | client_key: 0x041835D4, address: 0
but it's not creating a participant or topic. I can't receive my data.
Check that you don't have another serial program (putty, hterm, gtkterm, ...) connected to your device (at least not to that same UART). Also be sure that your hardware setup is correct, e.g. that you have GND connected between the two nodes when using a UART connection.
If you're using Eclipse: When compiling Eclipse says Error: Program "" not found in PATH
Right click your project -> Properties -> C/C++ Build -> Uncheck "Use default build command" and exchange ${cross_make} with a simple make
If you're using Eclipse:
I get an error that the program "" can not be executed
Right click your project -> Properties -> C/C++ Build:
Untick Use default build command.
Define Build command as: make
If you're using Eclipse and it says that it can't find the arm-none-eabi-gcc
You need to download and extract the toolchain. You can find it here: https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads
Then set up your Eclipse to know where it is:
Right click your project -> Properties -> MCU -> Arm Toolchains Paths:
Toolchain name: xPack GNU Arm Embedded GCC
Toolchain folder: path/to/your/arm-none-eabi-toolchain/bin
In the bin folder should be arm-none-eabi-gcc among others.
If it still doesn't work, try just opening the following menu: Right click your project -> Properties -> C/C++ Build -> Settings
/**
*****************************************************************************
**
** File : syscalls.c
**
** Author : Auto-generated by System workbench for STM32
**
** Abstract : System Workbench Minimal System calls file
**
** For more information about which c-functions
** need which of these lowlevel functions
** please consult the Newlib libc-manual
**
** Target : STMicroelectronics STM32
**
** Distribution: The file is distributed “as is,” without any warranty
** of any kind.
**
*****************************************************************************
** @attention
**
** <h2><center>© COPYRIGHT(c) 2019 STMicroelectronics</center></h2>
**
** Redistribution and use in source and binary forms, with or without modification,
** are permitted provided that the following conditions are met:
** 1. Redistributions of source code must retain the above copyright notice,
** this list of conditions and the following disclaimer.
** 2. Redistributions in binary form must reproduce the above copyright notice,
** this list of conditions and the following disclaimer in the documentation
** and/or other materials provided with the distribution.
** 3. Neither the name of STMicroelectronics nor the names of its contributors
** may be used to endorse or promote products derived from this software
** without specific prior written permission.
**
** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
** AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
** IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
** DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
** FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
** DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
** SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
** CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
** OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
**
*****************************************************************************
*/
// the code was modified by Fynn Boyer
/* Includes */
#include <sys/stat.h>
#include <stdlib.h>
#include <errno.h>
#include <stdio.h>
#include <signal.h>
#include <time.h>
#include <sys/time.h>
#include <sys/times.h>
/* Variables */
//#undef errno
extern int errno;
extern int __io_putchar(int ch) __attribute__((weak));
extern int __io_getchar(void) __attribute__((weak));
register char * stack_ptr asm("sp");
char *__env[1] = { 0 };
char **environ = __env;
extern char _estack; // see ld file
extern char _Min_Stack_Size; // see ld file
/* Functions */
void initialise_monitor_handles()
{
}
int _getpid(void)
{
return 1;
}
int _kill(int pid, int sig)
{
errno = EINVAL;
return -1;
}
void _exit (int status)
{
_kill(status, -1);
while (1) {} /* Make sure we hang here */
}
__attribute__((weak)) int _read(int file, char *ptr, int len)
{
int DataIdx;
for (DataIdx = 0; DataIdx < len; DataIdx++)
{
*ptr++ = __io_getchar();
}
return len;
}
__attribute__((weak)) int _write(int file, char *ptr, int len)
{
int DataIdx;
for (DataIdx = 0; DataIdx < len; DataIdx++)
{
__io_putchar(*ptr++);
}
return len;
}
caddr_t _sbrk(int incr) {
extern char __heap_start__ asm("end"); // Defined by the linker.
static char *heap_end;
char *prev_heap_end;
if (heap_end == NULL) heap_end = &__heap_start__;
prev_heap_end = heap_end;
if (heap_end + incr > &_estack - _Min_Stack_Size) {
__asm("BKPT #0\n");
errno = ENOMEM;
return (caddr_t)-1;
}
heap_end += incr;
return (caddr_t)prev_heap_end;
}
int _close(int file)
{
return -1;
}
int _fstat(int file, struct stat *st)
{
st->st_mode = S_IFCHR;
return 0;
}
int _isatty(int file)
{
return 1;
}
int _lseek(int file, int ptr, int dir)
{
return 0;
}
int _open(char *path, int flags, ...)
{
/* Pretend like we always fail */
return -1;
}
int _wait(int *status)
{
errno = ECHILD;
return -1;
}
int _unlink(char *name)
{
errno = ENOENT;
return -1;
}
int _times(struct tms *buf)
{
return -1;
}
int _stat(char *file, struct stat *st)
{
st->st_mode = S_IFCHR;
return 0;
}
int _link(char *old, char *new)
{
errno = EMLINK;
return -1;
}
int _fork(void)
{
errno = EAGAIN;
return -1;
}
int _execve(char *name, char **argv, char **env)
{
errno = ENOMEM;
return -1;
}