API

From STM32duino wiki
Jump to: navigation, search

Differences compared to Arduino API

Data types

  • int: On the Arduino Uno (and other ATMega based boards) an int stores a 16-bit (2-bytes) value while on STM32 based boards an int stores a 32-bit (4-bytes) value.
  • double: On the Uno and other ATMEGA based boards double occupies 32-bit (4-bytes), same as float while on STM32 based boards a double occupies 64-bit (8-bytes).

PWM

Arduino boards support 8-bit PWM, which means that calls to analogWrite() take values between 0 (always off) and 255 (always on).

STM32 boards support 16-bit PWM so values can range from 0 (always off) and 65535 (always on).

For backward compatibility, in STM32duino, analogWrite() still takes values between 0 (always off) and 255 (always on); the new pwmWrite() function provides instead support to the higher resolution 0 (always off) and 65535 (always on).

ADC

Arduino boards support 10-bit ADC, which means that calls to analogRead() will return values between 0 and 1023. The Maple supports 12-bit ADC, so the same call will instead return values between 0 and 4095.

Important information about global constructor methods

Classes, including libraries, must not called pinMode() or digitalWrite() or digitalRead() etc, or any similar function in a global constructor. Do not store references to pins in global constructors

This is because the mapping of the pins is dynamic, and is not guaranteed to be initialized for global constructor code.

Libraries often do not function because they attempt to call pinMode in their constructor.

Serial & USB Serial

Serial USB is enabled for all F103 boards when uploading using the bootloader, it is also available when uploading by ST-Link (SWD) In these cases:

  • Serial.print("Hello world"); will print via Serial USB (CDC).
  • Serial1 prints to hardware USART 1
  • Serial2 prints to hardware USART 2
  • etc

When uploading via "Serial" (external USB to Serial adaptor connected to PA9 and PA10 (USART1) on the STM32):

  • Serial.print("Hello world"); will print to hardware USART1 (the one the code was uploaded using)
  • Serial1 prints to hardware USART 2
  • etc

Note. Some boards, e.g. Nucleo F103RB have special serial mapping, because these boards need to have hardware modification to make Serial usable.

The Serial <-> USART mapping is defined in file "variants/<board_name>/board.cpp".

Pin access

Pin Modes

  • OUTPUT: Basic digital output: when the pin is HIGH, the voltage is held at +3.3v (Vcc) and when it is LOW, it is pulled down to ground.
  • OUTPUT_OPEN_DRAIN: In open drain mode, the pin indicates “low” by accepting current flow to ground and “high” by providing increased impedance.
  • INPUT: Basic digital input.
  • INPUT_ANALOG: This is a special mode for when the pin will be used for analog (not digital) reads.
  • INPUT_PULLUP: The state of the pin in this mode is reported the same way as with INPUT, but the pin voltage is gently “pulled up” towards +3.3v.
  • INPUT_PULLDOWN: The state of the pin in this mode is reported the same way as with INPUT, but the pin voltage is gently “pulled down” towards 0v.
  • INPUT_FLOATING: Synonym for INPUT.
  • PWM: This is a special mode for when the pin will be used for PWM output (a special case of digital output).
  • PWM_OPEN_DRAIN: Like PWM, except that instead of alternating cycles of LOW and HIGH, the voltage on the pin consists of alternating cycles of LOW and floating (disconnected).

Reading from & Writing to pins

You can use the standard analogWrite, digitalWrite, analogRead & digitalRead from Arduino, but they can be slow, there are some faster alternatives. These are by directly going to the GPIO ports, which are 16bits wide (so 16 pins per port)

gpio_write_bit

This is a function you can call, that doesn't take the pinnumber, but the GPIOPort, and which pin of the port you want to access.
It's a lot faster than the digitalWrite function
gpio_write_bit(GPIOB, 0, LOW);

Direct access to the registers

here are the registeres with which you can read/write the state of the pins

BSRR

Sets & Resets pins. It's a register that's 32 bits wide, the first 16 bits will set a pin to "1" when value 1 is written to it, the next 16 bits will set a pin to 0 when a value is written to it. Set pin 0 of port A high
GPIOA->regs->BSRR = 1;
Reset pin 0 of Port A to low
GPIOA->regs->BSRR = 1<<16;

BRR

Resets pins. It's a register that's 16 bits wide, basically matches the second half of the BSRR register. Reset pin 0 of Port A
GPIOA->regs->BRR = 1;

ODR

Output data register, when writing to it, sets the value of ALL the pins to what you wrote to the register: Set pin 0 of port A high, all the others low
GPIOA->regs->ODR = 1;

IDR

Input data register, returns the value of ALL the pins related to the specified port: Check if pin n (n=0..15) of Port A is high
if(GPIOA->regs->IDR & (1<<n))

Storing data in flash memory

Declare variables as const to put them into flash memory.

This old method (below) is deprecated

The __FLASH__ macro to store variables into the flash memory, instead of the RAM,
example:
uint32 array[] __FLASH__ = {0, 1, 2};