STM32CubeDuino

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.

Getting Started

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.

Done

Special Macros

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.

Implementation Notes

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 int overloads for functions and methods have been omitted.
__HAL_RCC_SYSCFG_CLK_ENABLE() and __HAL_RCC_PWR_CLK_ENABLE() are called before main(). USB, HardwareSerial, _TimerPinMap::f1PinModeTimer() and enableGpioClock() require that these clocks are enabled. Keep that in mind when during these clocks off.

Hardware Design Hints

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.

FAQ

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_FLASH and STM32CUBEDUINO_FLOAT_STRING in the board definition or via build flag. This trades off execution speed for flash size.
Adding the build flag -ffast-math can improve code size.
Avoid floating point math all together.
Try to disable unused periphery and functions by defining STM32CUBEDUINO_DISABLE_PRINTF_FLOAT for 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-math for 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 const where 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.

Issues

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

License

See LICENSE.

Contributions

No content contributions are accepted. Please file a bug report or feature request instead.
This decision was made in consideration of the used license.

daniel-starke/STM32CubeDuino