Port of the Arduino API based on the STM32 Cube framework.
This library aims to provide high compatibility to the original Arduino AVR framework, or at least
Arduino SAMD framework, while maintaining a simple, stable and lightweight implementation.
Issues of the Arduino API (not its implementation) are adopted were applicable for highest compatibility.
To ensure easy adaption between existing and custom STM32 based boards, STM32 Cube framework
is used as backend API. Middleware layers are avoided to reduce function overhead. Only the Cube
Low Layer and Hardware Abstraction Layer is used together with the CMSIS API.
Please note that this only provides the Arduino API, not its whole environment. Hence, there is
no special pre-processor pass to handle .ino files. You need to write C/C++ compliant code.
Also note that this is not a modified version of STM32duino or Mbed. The used implementation approach is fundamentally different, to provide better support for custom boards.
This project is not affiliated with Arduino AG, STMicroelectronics International NV, or any of its affiliates.
A getting started guide can be found here.
Some small examples are also included here.
Note that the examples are configured to be compiled from within this repository.
- Custom board.ini Creation Script
- Basic Arduino API
- Time
- Digital I/O
- WInterrupt
- WMath
- WCharacter
- WString
- Printable
- Stream
- HardwareSerial
- binary.h
- serialEventRun()
- ADC (still missing support for SDADC)
- DAC (analogWrite())
- PWM (analogWrite())
- HardwareTimer
- tone()/noTone()
- pulseIn()/pulseInLong()
- shiftOut()/shiftIn()
- SPI
- I2C
- EEPROM
- EEPROM flash emulation
- Pluggable USB
- USB CDC
- USB HID
- CAN
- Version.h
- boot to system bootloader via USB CDC 1200 Baud touch
- SoftwareSerial
- USBHost
- Documentation
- License
- keywords.txt
- Example Board
- disabling macros
- add support for STM32MP1 (needs PlatformIO support)
- add support for STM32U5 (needs PlatformIO support)
- add support for STM32WL (needs PlatformIO support)
- add support for STM32WB (needs PlatformIO support)
- GitHub Release
| Name | Meaning |
|---|---|
ARDUINO |
Defines the compatible Arduino version. |
ARDUINO_API_VERSION |
Defines the compatible Arduino API version. |
ARDUINO_ARCH_STM32 |
Defines the Arduino target architecture. |
STM32CUBEDUINO |
Defines the version of the STM32CubeDuino library as string. |
STM32CUBEDUINO |
Defines the version of the STM32CubeDuino library as string. |
STM32CUBEDUINO_MAJOR |
Defines the major version number of the STM32CubeDuino library. |
STM32CUBEDUINO_MINOR |
Defines the minor version number of the STM32CubeDuino library. |
STM32CUBEDUINO_PATCH |
Defines the patch version number of the STM32CubeDuino library. |
STM32CUBEDUINO_VERSION(x, y, z) |
Transforms the given major, minor and patch version number into a single number for comparison. |
STM32CUBEDUINO_VERSION_CODE |
Defines the version of the STM32CubeDuino library as single number for comparison. |
STM32CUBEDUINO_SMALL_FLASH |
May be defined by the user to trade off speed for small flash usage. |
STM32CUBEDUINO_FLOAT_STRING |
May be defined by the user to implement only single precision float to string conversion functions. |
STM32CUBEDUINO_LEGACY_API |
May be defined by the user to remove non-Arduino functions for better compatibility. |
STM32CUBEDUINO_INTERNALS |
May be defined by the user to get access to some internal functions. These are not automatically exported. The user needs to declare a function prototype to access these. |
STM32CUBEDUINO_CUSTOM_IRQ_HANDLERS |
May be defined by the user to define custom STM32 HAL IRQ handlers. All STM32CubeDuino specific handlers will be disabled. |
STM32CUBEDUINO_MAP_ALL_IRQS |
May be defined by the user to unconditionally map all STM32 HAL IRQ handlers to STM32CubeDino specific ones. |
STM32CUBEDUINO_DISABLE_ADC |
May be defined by the user to disable ADC related STM32CubeDino functions. |
STM32CUBEDUINO_DISABLE_CDC |
May be defined by the user to disable USB serial (CDC) related STM32CubeDino functions. |
STM32CUBEDUINO_DISABLE_DAC |
May be defined by the user to disable DAC related STM32CubeDino functions. |
STM32CUBEDUINO_DISABLE_EEPROM |
May be defined by the user to disable EEPROM related STM32CubeDino functions. |
STM32CUBEDUINO_DISABLE_EXTI |
May be defined by the user to disable external interrupt related STM32CubeDino functions. |
STM32CUBEDUINO_DISABLE_I2C |
May be defined by the user to disable I2C related STM32CubeDino functions. |
STM32CUBEDUINO_DISABLE_PWM |
May be defined by the user to disable PWM related STM32CubeDino functions. |
STM32CUBEDUINO_DISABLE_PRINTF_FLOAT |
May be defined by the user to disable float support in printf like functions. |
STM32CUBEDUINO_DISABLE_SCANF_FLOAT |
May be defined by the user to disable float support in scanf like functions. |
STM32CUBEDUINO_DISABLE_SERIAL |
May be defined by the user to disable hardware serial related STM32CubeDino functions. |
STM32CUBEDUINO_DISABLE_SPI |
May be defined by the user to disable SPI related STM32CubeDino functions. |
STM32CUBEDUINO_DISABLE_STRING |
May be defined by the user to disable the Arduino String class and related functions. |
STM32CUBEDUINO_DISABLE_TIMER |
May be defined by the user to disable hardware timer related STM32CubeDino functions (not PWM). |
STM32CUBEDUINO_DISABLE_USB |
May be defined by the user to disable USB related STM32CubeDino functions. |
STM32CUBEDUINO_DISABLE_USB_CDC |
May be defined by the user to disable USB CDC related STM32CubeDino functions. |
NO_GPL |
May be defined by the user to exclude GPL licensed code. This affects only support functions included for better Arduino AVR compatibility. |
SERIAL_RX_BUFFER_SIZE |
May be defined by the user to change the serial reception buffer size. Defaults to 64 bytes. |
SERIAL_TX_BUFFER_SIZE |
May be defined by the user to change the serial transmission buffer size. Defaults to 64 bytes. |
TWOWIRE_RX_BUFFER_SIZE |
May be defined by the user to change the I2C reception buffer size. Defaults to 32 bytes. |
TWOWIRE_TX_BUFFER_SIZE |
May be defined by the user to change the I2C transmission buffer size. Defaults to 32 bytes. |
SPI_TRANSFER_TIMEOUT |
May be defined by the user to change the SPI timeout in milliseconds. Set to HAL_MAX_DELAY for no timeout. Defaults to 1000ms. |
ACTIVATE_USB_PORT |
May be defined by the user with custom logic to force a USB enumeration, e.g. by pulling down D+. |
USB_EP_SIZE |
May be defined by the user to change the USB single endpoint size. Defaults to 32 or 64 bytes depending on the target platform. |
USB_RX_SIZE |
May be defined by the user to change the USB reception buffer size. This needs to be at least 2 * USB_EP_SIZE. Defaults to 2 * USB_EP_SIZE. |
USB_TX_SIZE |
May be defined by the user to change the USB transmission buffer size. This needs to be a multiple of USB_EP_SIZE and at least two times its size. Defaults to 2 * USB_EP_SIZE. |
USB_PRODUCT |
May be defined by the user to change the USB product name. Defaults to "USB IO Board". |
USB_MANUFACTURER |
May be defined by the user to change the USB manufacturer name. Defaults to "STMicroelectronics" depending on USB_VID. |
I_CACHE_DISABLED |
May be defined by the user to disable instruction cache. |
D_CACHE_DISABLED |
May be defined by the user to disable data cache. |
HAVE_HWSERIAL0 |
Defined if the hardware serial API is available. |
HAVE_CDCSERIAL |
Defined if the CDC (serial USB) API is available. |
USBCON |
Defined if the USB API is available. |
USB_ENDPOINTS |
Defined with the number of available USB endpoints. |
EXTI_IRQ_PRIO |
Needs to be defined in board.hpp to set the priority for external interrupts. |
EXTI_IRQ_SUBPRIO |
Needs to be defined in board.hpp to set the sub-priority for external interrupts. |
I2C_IRQ_PRIO |
Needs to be defined in board.hpp to set the priority for I2C interrupts. |
I2C_IRQ_SUBPRIO |
Needs to be defined in board.hpp to set the sub-priority for I2C interrupts. |
SYSTICK_IRQ_PRIO |
Needs to be defined in board.hpp to set the priority for SYSTICK interrupts. |
SYSTICK_IRQ_SUBPRIO |
Needs to be defined in board.hpp to set the sub-priority for SYSTICK interrupts. |
TIMER_IRQ_PRIO |
Needs to be defined in board.hpp to set the priority for TIMER interrupts. |
TIMER_IRQ_SUBPRIO |
Needs to be defined in board.hpp to set the sub-priority for TIMER interrupts. |
UART_IRQ_PRIO |
Needs to be defined in board.hpp to set the priority for UART/USART interrupts. |
UART_IRQ_SUBPRIO |
Needs to be defined in board.hpp to set the sub-priority for UART/USART interrupts. |
USB_IRQ_PRIO |
Needs to be defined in board.hpp to set the priority for USB interrupts. |
USB_IRQ_SUBPRIO |
Needs to be defined in board.hpp to set the sub-priority for USB interrupts. |
USB_VID |
Needs to be defined in board.hpp to set the USB vendor ID. E.g. 0x2341 for Arduino LLC. |
USB_PID |
Needs to be defined in board.hpp to set the USB product ID. E.g. 0x8036 for Leonardo (CDC ACM, HID). |
USB_TX_TRANSACTIONAL |
Needs to be defined in board.hpp if the used STM32 HAL library handles multi-packet USB transactions with a single HAL_PCD_DataInStageCallback() call. |
- All code is written for C++14 and C18.
- The used DAC/ADC/Timer (PWM) instance for each pin is the one with the lowest instance number available for that pin by default.
- Only USB FS and no USB HS or ULPI is supported for chips with USB peripheral
- Proper registration of the USB VID and PID is need to publish a USB product. See here, here and here.
setAltFunction()may be overwritten by the user to allow a different alternate function number to remap mapping for STM32F1.setAdcFromPin()may be overwritten by the user to define a different pin to ADC mapping._TimerPinMap::_TimerPinMap(const uint32_t pin)may be overwritten by the user to define a different pin to timer mapping.- Timer0 may be overwritten by the user to use a different timer for internal functions. The other timers (e.g. Timer1) are not defined by default.
- DAC pin mapping cannot be changed as it is the same for all targets and requires no changes.
- STM32CubeDuinoIrqHandlerForXXX() functions may be overwritten by the user to handle interrupt of the corresponding STM32 HAL instance XXX.
- getIrqNumFor(XXX) returns the IRQ number of the given STM32 HAL instance XXX, whereas XXX matches only pre-defined names like TIM1.
- clearNvicIrqFor(XXX) clears the pending interrupt bit for the given STM32 HAL instance XXX, whereas XXX matches only pre-defined names like TIM1.
- There can be only one interrupt callback function attached per pin, regardless of the port.
- Additional
intoverloads for functions and methods have been omitted. __HAL_RCC_SYSCFG_CLK_ENABLE()and__HAL_RCC_PWR_CLK_ENABLE()are called beforemain(). USB,HardwareSerial,_TimerPinMap::f1PinModeTimer()andenableGpioClock()require that these clocks are enabled. Keep that in mind when during these clocks off.
- Try to configure your clocks and pinout in STM32CubeIDE before starting the hardware design, to find design flews due to operation restrictions in an early development stage.
- Check the chip specific datasheet carefully for the recommended power setup. Missing backup/filtering/decoupling capacities can have a strong influence on the operation stability.
- All STM32 chips have a correct USB line termination resistor for the correct impedance included (see AN4879 Q&A section).
- Some STM32 chips require an external 1.5kΩ pull-up for USB D+ to operate correctly.
- One 5.1kΩ pull-down on CC1 and one on CC2 can be applied to use a USB-C connector in USB2.0 mode.
- The needed values for the passive components for an external crystal can be calculated via this calculator in accordance to AN2867.
- The capacitors are mainly needed to stimulate the crystal and may work well with different values as well.
- The resistor value can be less then given but should not be higher.
- See AN2606 for details regarding the possible boot configurations and programming modes (e.g. not every chip can be programmed via USB).
- The edge detection period for external interrupts may be shorter than a clock period. Make sure to add sufficient electrical filtering.
Q: Can I use STM32CubeDuino with the Arduino IDE?
A: No. This would require some code changes in the Arduino IDE. Therefore, support is currently only given for PlatformIO.
Q: Writing to HardwareSerial from within an interrupt handler gives me broken data. What can I do?
A: This is usually the case if the UART/USART/LPUART IRQ handler has a priority lower or equal to the one in question. Assign a higher priority (lower value) to UART or increase the buffer size for HardwareSerial.
Q: Can I use compiler xyz instead of GCC?
A: Most likely not. The code was written with the assumption that GCC is used to simplify code design in several places.
Q: How can I simply reduce the binary size?
A: There are several simple ways to reduce the needed flash size. Some with speed penalties.
- Define the macros
STM32CUBEDUINO_SMALL_FLASHandSTM32CUBEDUINO_FLOAT_STRINGin the board definition or via build flag. This trades off execution speed for flash size. - Adding the build flag
-ffast-mathcan improve code size. - Avoid floating point math all together.
- Try to disable unused periphery and functions by defining
STM32CUBEDUINO_DISABLE_PRINTF_FLOATfor example. See the complete list of disabling macros above. - Use the compiler flag
-Os. This should be active by default.
Q: How can I improve execution speed/throughput?
A: The biggest benefit usually has the use of better algorithm. Minor improvements can be archives with the following steps.
- Add the build flag
-ffast-mathfor faster, but less IEEE 754 conformance in floating point math. - Use FIFO sizes to a power of 2 (e.g. for
USB_TX_SIZE). This makes the compiler use simple binary AND which is much faster than integer division. - Use larger periphery buffers.
- Try offloading tasks to DMA channels. Note that the Arduino API offers no functions for this. You can use the STM32 HAL API for example.
- Pass larger structures by reference/pointer instead of copy. Pass native types (e.g.
int) by value. - Use
constwhere possible. - Enable instruction and data cache via STM32 HAL API if available for the target MCU. E.g. via
SCB_EnableICache(). Both are usually enabled by default in STM32CubeDuino.
Q: How do I generate a custom initVariant() function for my board?
A: Download the STM32CubeIDE. Create a new STM32 Project for the used chip in there and activate all relevant peripherals. Complete the clock configuration and generate the code. The content from the generated SystemClock_Config() function in main.c is the base for the new initVariant() function. Finally, replace all calls to Error_Handler() with systemErrorHandler(). See also Getting Started.
Q: Passing -flto to the compiler and linker breaks my build. The firmware is not starting anymore.
A: This is most likely due to an old bug in binutils. Try to update to a more recent toolchain.
- periphery locking is not implemented for STM32MP1 and other multi-core MCUs
- handling of analog control register ASC0 is missing in
pinModeEx() __HAL_LOCK()is basically broken but may be fixed in your version.- PWM output setup creates spikes (maybe due to
TIM_CCxChannelCmd(htim->Instance, Channel, TIM_CCx_ENABLE); /* Enable the Capture compare channel */) - Px_xC Pins are not yet addressable
See LICENSE.
No content contributions are accepted. Please file a bug report or feature request instead.
This decision was made in consideration of the used license.