.. index:: stm32f103,blue pill,olimex-p103

.. _stm32f103-page:

STM32F103 MCU
=============
This old but still very capable chip is used in various :ref:`cheap Chinese boards<blue-pill>` and some decent boards by STM (discovery, Nucleo) and Olimex etc.

.. warning:: There are a lot of :ref:`cheap Chinese boards<blue-pill>` for sale that don't work because they use fake or bad chips. I always recommend using a trusted vendor, such as STM, Olimex, Seed Studio, Arrow.com etc if you want a STM32F103 Board. Arrow.com are a very reputable source of boards and chips.

Hardware Handshaking Image
--------------------------
Because this MCU is still so popular I have made up a special STM32F103 RA Forth image (mecrisp-stellaris-stm32f103-rts_cts.bin) with *hardware handshaking* using the Mecrisp-Stellaris 2.5.1 stm32f103-RA kernel.
::

 MS RA 2.5.1 tpmod for STM32F103 by Matthias Koch

How does it work ?
^^^^^^^^^^^^^^^^^^
When Source Code is uploaded to a MCU running Forth, every "Word" is compiled on the chip as it is received and this takes a finite amount of time depending on the complexity of the Word, the speed of the MCU and the speed of the serial Baud rate.

At higher Baud rates (such as 115200) if the serial data stream to the chip is too fast to be compiled, Forth will "lock up" and the board will need to be reset to get it working again.

To prevent this "lock up" we have a few strategies:

1. End of Line Delay: Implemented at the serial terminal, (usually about 200 milliseconds) stops the PC from uploading source code to the MCU for 200 ms after *every line of code*! This gives the on chip compiler time to digest longer more complex Words, however this EOL delay is applied after *every line* whether needed or not and will significantly slow down large Source Code uploads.

2. RTS/CTS hardware handshaking: This uses USART2 "control signals" named "RTS" and "CTS" to synchronise data transmissions between the PC and the MCU.

=========== ========== ========   
SIGNAL      INPUT      OUTPUT
=========== ========== ========
RTS                    YES
CTS         YES        
=========== ========== ========

.. note:: Don't short OUTPUTS to +V or 0v while testing. This is OK with INPUTS however.
  
At the MCU, RTS is asserted (tied LOW) as long as USART2 is ready to receive new data. When the USART2 receive register is full, RTS is de-asserted (raised HIGH), indicating that the transmission (from the PC) is expected to stop at the end of the current frame.

At the PC, the CTS line is connected to the MCU RTS line, and if the CTS line is held LOW, the PC is free to send data to the MCU via your serial terminal. However if the CTS line is raised HIGH the PC will stop sending data until it is LOW again.

This way no wasteful fixed length EOL delay is needed because the MCU will simply pause the Terminal sending data only when it needs to, making this method the fastest way to upload Source Code.


.. note:: This Image uses USART2 on the STM32F103 which is DIFFERENT to the normal USART1 used on this MCU by Mecrisp-Stellaris. The reason is that on this MCU the USART1 RTS control signal is used by the USB system and therefore not available. Connect a :ref:`3.3v/USB Dongle<6pin-serial-usb-dongle>` between your PC and the MCU board as shown below. Make sure the dongle has a CTS connection as well as the usual RX/TX pins and power.

RTS/CTS handshaking:
~~~~~~~~~~~~~~~~~~~~
You don't have to use the handshaking for the Kernel to work, but it will need a SLOW 200mS "End Of Line Delay" for your serial terminal if you don't. No EOL delay is needed with hardware handshaking as the MCU will tell the PC to stop uploading source code as required while compiling.

Baud Rate is 115200 Baud. 

=========== ============= =====================
Gpio	    MCU Signal    3.3v/USB Dongle
=========== ============= =====================
PA1         RTS           CTS   
PA2         TX            RX
PA3         RX            TX
=========== ============= =====================


.. note:: Don't forget to activate your serial terminal RTS/CTS hardware handshaking mode.

Picocom serial terminal hardware handshaking example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Change the "/dev/cuaU0" to suit your (Unix) machine.
::

 picocom -b 115200 /dev/cuaU0  --omap delbs,crlf --flow h --send-cmd "ascii-xfr -s -l200" &


Other Kernel Mods
-----------------

   * Added CR to the standard LF so you don't have to do that in your terminal to prevent "stair stepping"

   
DOWNLOADS 
---------

64KB Flash Image
^^^^^^^^^^^^^^^^
This modified but base image runs fine in a 64KB Flash mcu.

:download:`Image (20.5KB) <kernels/mecrisp-stellaris-stm32f103-rts_cts.bin>`

:download:`MD5SUM<kernels/md5.mecrisp-stellaris-stm32f103-rts_cts.bin>`

.. _stm32f103-dev-image:

128KB Developers Image
----------------------
This 128KB Developers Image (b6feae9831fcabcad8f45442f98d8c32) is preloaded with tons of development support, see below for details. It uses the 64KB Kernel above, so it includes RTS/CTS handshaking on the same GPIO pins etc,

Download it here (44KB): https://sourceforge.net/projects/mecrisp-stellaris-folkdoc/files/STM32F103-developers-image.tar.gz/download

Kernel Properties
^^^^^^^^^^^^^^^^^
* Size: 99184 Bytes
* Requires 128KB Flash version of the STM32F103, ie Olimex-P103, Blue Pill etc.
* Clock is internal RC 8MHz
 
b6feae9831fcabcad8f45442f98d8c32 Image Contains
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* every single STM32F103 register memory map and pretty print with legends
* Arm Core registers STK. and SCB. with memory map and pretty print with legends

.. note:: See b6feae9831fcabcad8f45442f98d8c32.README for Specific Notes regarding Mecrisp-Stellaris Kernel b6feae9831fcabcad8f45442f98d8c32.bin and see b6feae9831fcabcad8f45442f98d8c32.words4.txt for the complete word list.

Words
-----

free
^^^^
::

   free (bytes) 
   FLASH.. TOTAL REPORTED: 131072 USED: 99176 FREE: 31896 
   RAM.... TOTAL PRESET: 20000 USED: 1112 FREE: 18888

bin.
^^^^
::

   1000 bin. 
   3322222222221111111111
   10987654321098765432109876543210 
   00000000000000000000001111101000
   ok.

see
^^^
::

   see + 
   00001F20: CF01  ldmia r7 { r0 }
   00001F22: 1836  adds r6 r6 r0
   00001F24: 4770  bx lr
   Bytes: 6  ok.

words4
^^^^^^
::
 
   --- MS RA 2.5.1 tpmod ---
   2dup                2drop               2swap               2nip                
   2over               2tuck               2rot                2-rot               
   2>r                 2r>                 2r@                 2rdrop              
   d2/                 d2*                 dshr                dshl                
   dabs                dnegate             d-                  d+                  
   s>d                 um*                 m*                  ud*                 
   udm*                */                  */mod               u*/                 
   u*/mod              um/mod              m/mod               ud/mod              
   d/mod               d/                  f*                  f/                  
   2!                  2@                  du<                 du>                 
   d<                  d>                  d0<                 d0= 
   ... lots more Words
   imm8.               imm3<<1.            imm5<<1.            imm8<<1.            
   imm3<<2.            imm5<<2.            imm7<<2.            imm8<<2.            
   destination-r0      disasm              memstamp            disasm-step         
   seec                see                 pr                   ok.

ansi colors
^^^^^^^^^^^
For use with the terminal: black, red, green, yellow, blue, magenta, cyan, white

Every single STM32F103 peripheral
---------------------------------
Register can be pretty printed in real time with legends.

::

   PWR.
   RCC.
   GPIOA.
   GPIOB.
   GPIOC.
   GPIOD.
   AFIO.
   EXTI.
   DMA1.
   DMA2.
   SDIO.
   RTC.
   BKP.
   IWDG.
   WWDG.
   TIM1.
   TIM2.
   TIM3.
   TIM4.
   I2C1.
   I2C2.
   SPI1.
   SPI2.
   USART1.
   USART2.
   USART3.
   ADC1.
   CAN.
   DBG.
   CRC.
   FLASH.
   NVIC.
   USB.

Example 1:
----------
::
 
 gpioa. 
 GPIOA_CRL (read-write) $44444AA4 
 3|3|2|2|2|2|2|2|2|2|2|2|1|1|1|1|1|1|1|1|1|1|
 1|0|9|8|7|6|5|4|3|2|1|0|9|8|7|6|5|4|3|2|1|0|9|8|7|6|5|4|3|2|1|0 
 0 1 0 0 0 1 0 0 0 1 0 0 0 1 0 0 0 1 0 0 1 0 1 0 1 0 1 0 0 1 0 0
 
 GPIOA_CRH (read-write) $88844444 
 3|3|2|2|2|2|2|2|2|2|2|2|1|1|1|1|1|1|1|1|1|1|
 1|0|9|8|7|6|5|4|3|2|1|0|9|8|7|6|5|4|3|2|1|0|9|8|7|6|5|4|3|2|1|0 
 1 0 0 0 1 0 0 0 1 0 0 0 0 1 0 0 0 1 0 0 0 1 0 0 0 1 0 0 0 1 0 0
 
 GPIOA_IDR (read-only) $00001F78 
 3|3|2|2|2|2|2|2|2|2|2|2|1|1|1|1|1|1|1|1|1|1|
 1|0|9|8|7|6|5|4|3|2|1|0|9|8|7|6|5|4|3|2|1|0|9|8|7|6|5|4|3|2|1|0 
 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 0 1 1 1 1 0 0 0
 
 GPIOA_ODR (read-write) $0000A000 
 3|3|2|2|2|2|2|2|2|2|2|2|1|1|1|1|1|1|1|1|1|1|
 1|0|9|8|7|6|5|4|3|2|1|0|9|8|7|6|5|4|3|2|1|0|9|8|7|6|5|4|3|2|1|0 
 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0
 
 GPIOA_BSRR (write-only) $00000000 
 3|3|2|2|2|2|2|2|2|2|2|2|1|1|1|1|1|1|1|1|1|1|
 1|0|9|8|7|6|5|4|3|2|1|0|9|8|7|6|5|4|3|2|1|0|9|8|7|6|5|4|3|2|1|0 
 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
 
 GPIOA_BRR (write-only) $00000000 
 3|3|2|2|2|2|2|2|2|2|2|2|1|1|1|1|1|1|1|1|1|1|
 1|0|9|8|7|6|5|4|3|2|1|0|9|8|7|6|5|4|3|2|1|0|9|8|7|6|5|4|3|2|1|0 
 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
 
 GPIOA_LCKR (read-write) $00000000 
 3|3|2|2|2|2|2|2|2|2|2|2|1|1|1|1|1|1|1|1|1|1|
 1|0|9|8|7|6|5|4|3|2|1|0|9|8|7|6|5|4|3|2|1|0|9|8|7|6|5|4|3|2|1|0 
 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
  ok.

Example 2:
----------
::
 
 GPIOA_ODR.
 GPIOA_ODR (read-write) $0000A000 
 3|3|2|2|2|2|2|2|2|2|2|2|1|1|1|1|1|1|1|1|1|1|
 1|0|9|8|7|6|5|4|3|2|1|0|9|8|7|6|5|4|3|2|1|0|9|8|7|6|5|4|3|2|1|0 
 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0
  ok.

System Control Block
--------------------
Pretty print with legends in real time.
::
 
 scb. 
 SCB_CPUID () $411FC231 
 SCB_CPUID BASE REGISTER                                             
                        | CONS- |                                
 --IMPLEMENTER--|VARIANT|-TANT--|------PART NUMBER------|RE-     
 3|3|2|2|2|2|2|2|2|2|2|2|1|1|1|1|1|1|1|1|1|1|           |-VISION 
 1|0|9|8|7|6|5|4|3|2|1|0|9|8|7|6|5|4|3|2|1|0|9|8|7|6|5|4|3|2|1|0 
 0 1 0 0 0 0 0 1 0 0 0 1 1 1 1 1 1 1 0 0 0 0 1 0 0 0 1 1 0 0 0 1
 
 SCB_ICSR () $00000000 
 INTERRUPT CONTROL AND STATE REGISTER                            
 Provides:                                                       
 *A set-pending bit for the Non-Maskable Interrupt NMI exception 
 *Set-pending and clear-pending bits for the PendSV and SysTick  
 exceptions.                                                     
 Indicates:                                                      
 *The exception number of the exception being processed          
 *Whether there are preempted active exceptions                  
 *The exception number of the highest priority pending exception 
 *Whether any interrupts are pending.                            
 N                 I                                             
 M     P P P P     S                                             
 I     E E E E     R                                             
 P     N N N N     P                                             
 E     D D D D     E                                             
 N     S S S S     N                                             
 D     V V T T     D                                             
 S     S C S C     I                                             
 E     E L E L     N                                             
 T     T R T R     G        |------VECT PENDING-----|VECT ACTIVE 
 3|   |2|2|2|2|   |2|       |1|1|1|1|1|1|           |----------- 
 1|~~~|8|7|6|5|~~~|2|~~~~~~~|7|6|5|4|3|2|~~~~~~~~~~~|5|4|3|2|1|0 
 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
 
 SCB_AIRCR () $FA050000 
 APPLICATION INTERRUPT AND RESET CONTROL REGISTER            V   
 provides endian status for data accesses and reset          E   
 control of the system.                                    S C   
                                 E                         Y T   
                                 N                         S C   
                                 D                         R L   
                                 I                         E R   
 To write to this register, you  A                         S A   
 must write $5FA to the VECTKEY  N                         E C   
 field FIRST.                    E                         T T   
                                 S                         R I   
 -----------VECTKEY-------------|S|                        E V   
 3|3|2|2|2|2|2|2|2|2|2|2|1|1|1|1|1|                        Q E   
 1|0|9|8|7|6|5|4|3|2|1|0|9|8|7|6|5|~~~~~~~~~~~~~~~~~~~~~~~|2|1|~ 
 1 1 1 1 1 0 1 0 0 0 0 0 0 1 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
 
 SCB_SCR () $00000000 
 SYSTEM CONTROL REGISTER                                   S S   
                                                       S   L E   
 controls features of entry to and exit from           E   E E   
 LOW POWER state.                                      V   E P   
                                                       O   P O   
                                                       N     N   
                                                       P   D E   
                                                       E   E X   
                                                       N   E I   
                                                       D   P T   
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~|4|~|2|1|~ 
 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
 
 SCB_CCR () $00000000 
 CONFIGURATION AND CONTROL REGISTER                      U       
                                             S           N       
 read-only register and indicates some       T           A       
 aspects of the behavior of the              K           L       
 Cortex-M0 processor.                                    I       
                                             A           G       
                                             L           N       
                                             I           T       
                                             G           R       
                                            |N           P       
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~|9|~~~~~~~~~|3|~~~~~ 
 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
 
 SCB_SHPR2 () $00000000 
 System handler priority registers (SHPRx)                       
 The SHPR2-SHPR3 registers set the priority level, 0 to 192,     
 of the exception handlers that have configurable priority.      
 SHPR2-SHPR3 are word accessible.                                
 ----PRI_11-----|                                                
 3|3|2|2|2|2|2|2|                                                
 1|0|9|8|7|6|5|4|~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
 
 SCB_SHPR3 () $00000000 
 System handler priority registers (SHPRx)                       
 The SHPR2-SHPR3 registers set the priority level, 0 to 192,     
 of the exception handlers that have configurable priority.      
 SHPR2-SHPR3 are word accessible.                                
 ----PRI_11-----|                                                
 3|3|2|2|2|2|2|2|                                                
 1|0|9|8|7|6|5|4|~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
 ok.

Systick peripheral
------------------
Pretty print with legends in real time.
::
 
 stk. 
 STK_CSR () $00000000 
 SysTick control and status register                             
 The SysTick CSR register enables the SysTick features.          
                               C                                 
                               O                                 
                               U                           C     
                               N                           K T   
                               T                           S I E 
                               F                           O C N 
                               L                           U K A 
                               A                           R I B 
                               G                           C N L 
                              |1|                          E T|E 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~|6|~~~~~~~~~~~~~~~~~~~~~~~~~|2|1|0 
 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
 
 STK_RVR () $00000000 
 SysTick reload value register                                   
 The STK_RVR specifies the start value to load into the STK_CVR. 
                |--------------------RELOAD--------------------- 
                |2|2|2|2|1|1|1|1|1|1|1|1|1|1|                    
 ~~~~~~~~~~~~~~~|3|2|1|0|9|8|7|6|5|4|3|2|1|0|9|8|7|6|5|4|3|2|1|0 
 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
 
 STK_CVR () $00000000 
                                                                 
                                                                 
                                                                 
                                                                 
                                                                 
                                                                 
                                                                 
                |--------------------CURRENT-------------------- 
                |2|2|2|2|1|1|1|1|1|1|1|1|1|1|                    
 ~~~~~~~~~~~~~~~|3|2|1|0|9|8|7|6|5|4|3|2|1|0|9|8|7|6|5|4|3|2|1|0 
 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
 
 STK_CALIB () $40002328 
 SysTick calibration value register                              
 If calibration information is not known, calculate the          
 calibration value from the clock.                               
 N                                                               
 O S                                                             
 R K                                                             
 E E                                                             
 F W            |---------------------TENMS--------------------- 
 3|3|           |2|2|2|2|1|1|1|1|1|1|1|1|1|1|                    
 1|0|~~~~~~~~~~~|3|2|1|0|9|8|7|6|5|4|3|2|1|0|9|8|7|6|5|4|3|2|1|0 
 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 0 1 1 0 0 1 0 1 0 0 0
 
  ok.

.. _72mhz:

72 MHz Clock Word
-----------------
This Word utilizes the 8Mhz Crystal on all the popular boards and the MCU internal PLL to boost the clock to 72 MHz, which is nine times faster than the standard Mecrisp-Stellaris image. 

This standalone Word requires no other support and uses absolute addressing to be as small as possible. It is designed to be loaded first to speed up all subsequent operations. As a result the source isn't easy to grok, but at least it's well commented.

"72mhz" is configured for 115200 Baud and USART1, which is the Mecrisp-Stellaris default. Other speed and USART options are available but commented out.

It will work with any STM32F103 Kernel including my recent :ref:`Special STM32F103 image with RTS/CTS hardware handshaking<stm32f103-page>` and :ref:`128KB Flash STM32F103 image with RTS/CTS hardware handshaking<stm32f103-dev-image>` images with some option changes such as USART and Baud rate.

72Mhz Sourcecode
^^^^^^^^^^^^^^^^

.. raw:: html
   :file: code/72mhz-f103.fs.html

:download:`Download 72mhz-f103.fs <code/72mhz-f103.fs>`

.. _stm32f103-dev-image-video:

Video
^^^^^
There is also a realtime video showing how fast the :ref:`128KB Developers Image<stm32f103-dev-image>` lists all the Words on my Forth development system when the board is running at 72MHz. See: https://sourceforge.net/projects/mecrisp-stellaris-folkdoc/files/stm32f103-devkernel-wordlist%4072mhz.mp4/download

This video is also on Youtube at: https://www.youtube.com/watch?v=JuW_noOexng&feature=youtu.be

Summary
~~~~~~~

   * Hardware Handshaking
   * Gnu Screen terminal
   * Baud Rate: 460800
   * Clock is 72 MHz