BoardSupportPackageFirefly < MecrispCube

%DASHBOARD{ section="dashboard_start" }%
%DASHBOARD{ section="banner"
 image="%PUBURLPATH%/MecrispCube/MecrispCubeFirefly/header.jpg"
 title="Board Support Package for the Firefly BLE Development Board"
 titlestyle="color:#F00000;"
}%
%DASHBOARD{ section="box_start" title="Intro" width="485" height="200"}%
The board support package for the !STM32WB Firefly Development Board is restricted to the Arduino UNO R3 pin header and the onboard LED and switch (button). The !STM32 has much more capabilities then 16 digital I/O pins, 5 analog input pins, UART, SPI, and !I2C interfaces. But if you want to use the more advanced features you can use the !CubeMX to create source code for the internal peripherals. This project wants to show how to use the Cube Ecosystem for a Forth system (or vice versa) and can't implement all features and possibilities the !STM32WB has. It is a good starting point for your project.
%DASHBOARD{ section="box_end" }%
%DASHBOARD{ section="box_start" title="Contents" width="460" height="200"}%
%TOC%
%DASHBOARD{ section="box_end" }%
%DASHBOARD{ section="box_start"  width="992" height="600" }%
---+ Board Support Words

Defaults: Digital port pins D0 to D9 are inputs, except D6 and D8 are output for neopixel, D1 for UART Tx. D10, D11, D12, and D13 are for the SD card. You are free to use the GPIO pins for other purposes.
<pre>
led1!        ( n -- )    sets LED1 (blue)
led1@        ( -- n )    gets LED1 (blue)

switch1?     ( -- n )    gets switch1, closed=TRUE

dport!       ( n -- )    sets the digital output port (D0=bit0 .. D15=bit15).
dport@       ( -- n )    gets the digital input/output port (D0=bit0 .. D15=bit15).
dpin!        ( n a -- )  sets the digital output port pin (D0=0 .. D15=15, A0=16 .. A4=20)
dpin@        ( a -- n )  gets the digital input/output port pin 
dmod         ( u a -- )  sets the pin mode: 0 in, 1 in pull-up, 2 in pull-down, 3 out push pull, 4 out open drain, 
                                            5 out push pull PWM, 6 input capture, 7 output compare, 8 I2C

EXTImod      ( u a -- )  Sets for pin a (D2, D4, D7, D10) the EXTI mode u: 0 rising, 1 falling, 2 both edges, 3 none
EXTIwait     ( u a -- )  Wait for EXTI interrupt on pin a (D2, D4, D7, D10), timeout u in [ms]

pwmpin!      ( u a -- )  sets the digital output port pin a (D0=0, D1=1, A4=20) to a PWM value u (0..1000). Default frequency is 1 kHz, TIMER1
pwmprescale  ( u --  )   Sets the PWM prescale for TIMER1. 32 kHz / prescale, default 32 -> PWM frequency 1 kHz

ICOCprescale ( u -- )    Sets the input capture / output compare prescale for TIMER2. default 32 -> 32 MHz / 32 = 1 MHz, timer resolution 1 us
ICOCperiod!  ( u -- )    Sets the input capture / output compare (TIMER2) period. default $FFFFFFFF (4'294'967'295). 
                         When the up counter reaches the period, the counter is set to 0. 
                         For prescale 32 the maximum time is about 1 h 11 m
ICOCcount!   ( -- u )    Sets the input capture / output compare counter for TIMER2
ICOCcount@   ( u -- )    Gets the input capture / output compare counter for TIMER2
ICOCstart    ( -- )      Starts the ICOC period
ICOCstop     ( -- )      Stops the ICOC period
OCmod        ( u a -- )  Sets for pin a (D13=13, A2=18, A3=19) the Output Compare mode u: 0 frozen, 1 active level on match, 2 inactive level on match, 
                            3 toggle on match, 4 forced active, 5 forced inactive
    
OCstart      ( u a -- )  Starts the output compare mode for pin a with pulse u
OCstop       ( a -- )    Stops output compare for pin a
ICstart      ( u -- )    Starts input capture u: 0 rising edge, 1 falling edge, 2 both edges
ICstop       ( -- )      Stops input capture

waitperiod   ( -- )      wait for the end of the TIMER2 period
OCwait       ( a -- )    wait for the end of output capture on pin a
ICwait       ( u -- u )  wait for the end of input capture with timeout u, returns counter u

apin@        ( a -- u )  gets the analog input port pin (A0 .. A4). Returns a 12 bit value (0..4095) 

I2Cdev       ( u -- )           Sets the 7-bit I2C address
I2Cput       ( c-addr u -- )    put a message with length u from buffer at c-addr to the I2C slave device
I2Cget       ( c-addr u -- )    get a message with length u from I2C slave device to buffer at c-addr
I2Cputget    ( a1 u1 a2 u2 -- ) put a message with length u1 from buffer at a1 to the I2C slave device 
                                and get a message with length u2 from device to buffer at a2

SPIputget    ( a1 a2 u -- )     put a message with length u from buffer at a1 to the SPI slave device 
                                and get a message with length u from device to buffer at a2
SPIputc      ( char )           put a single char to the SPI slave device

</pre>
%DASHBOARD{ section="box_end" }%

%DASHBOARD{ section="box_start"  width="992" height="520" }%
---+ Using the Digital Port Pins (Input and Output)

This example is very similar to the Cosmac.McForth#Knight_Rider program. =dport!= and =dport@= set and get all 16 digital pins (D0 to D15) at once. You have to press the _SW1_ push button til D0 is set to cancel the operation. Be aware the D0 and D1 pins are shared with the UART.
<pre>
3 0 dmod   \ set D0 to Output
3 1 dmod   \ set D1 to Output
3 2 dmod   \ set D2 to Output
3 3 dmod   \ set D3 to Output
3 4 dmod   \ set D4 to Output
3 5 dmod   \ set D5 to Output
3 6 dmod   \ set D6 to Output
3 7 dmod   \ set D7 to Output
</pre>

 <table>
  <tr>
    <td>
<pre>
: left ( -- ) 
  7 0 do  
    dport@ shl dport!  
    100 osDelay drop  
  loop 
;
</pre>
    </td>
    <td>
<pre>
: right ( -- )
  7 0 do  
    dport@ shr dport!
    100 osDelay drop  
  loop 
;
</pre>
    </td>
    <td>
<pre>
: knightrider ( -- )
  1 dport! 
  begin 
    left right 
    switch1? \ or key?
  until 
  0 dport!
;
</pre>
    </td>
  </tr>
</table> 


Single port pin variant (no side effects on port pins D8 to D15):

 <table>
  <tr>
    <td>
<pre>
: left ( -- ) 
  7 0 do
    1 i dpin! 
    100 osDelay drop  
    0 i dpin!
  loop 
;
</pre>
    </td>
    <td>
<pre>
: right ( -- )
  8 1 do  
    1 8 i - dpin! 
    100 osDelay drop  
    0 8 i - dpin!
  loop 
;
</pre>
    </td>
    <td>
<pre>
: knigthrider ( -- )
  begin 
    left right 
    switch1? 
  until 
  0 0 dpin!
;
</pre>
    </td>
  </tr>
</table> 
%DASHBOARD{ section="box_end" }%

%DASHBOARD{ section="box_start"  width="992" height="650" }%
---+ Using the ADC (Analog Input Pins)

=apin@ ( a -- u )= returns the ADC value (12 bit, 0 .. 4095) from one of the analog pins A0 to A4 (0 .. 4). Here I use the A0 to control the delay.

 <table>
  <tr>
    <td>
<pre>
: left ( -- ) 
  7 0 do
    1 i dpin! 
    0 apin@ 10 / osDelay drop  \ delay depends on A0
    0 i dpin!
  loop 
;
</pre>
    </td>
    <td>
<pre>
: right ( -- )
  8 1 do  
    1 8 i - dpin! 
    0 apin@ 10 / osDelay drop  \ delay depends on A0
    0 8 i - dpin!
  loop 
;
</pre>
    </td>
  </tr>
</table> 

To get an idea how fast the ADC, RTOS, and the Forth program are. The =left= or =right= word takes about 125 us, the =knightrider= loop about 50 us (no osDelay). Pretty fast for my opinion.

CH1 yellow: D0 pin<br>
CH2 blue: D1 pin<br>
<img src="%ATTACHURLPATH%/TEK0012.png" alt="TEK0012.png" width="320" height="240" />

%DASHBOARD{ section="box_end" }%

%DASHBOARD{ section="box_start"  width="992" height="400" }%
---+ Using the PWM (Analog Output Pins)
Only three port pins are supported so far. The 16 bit TIMER1 is used for the timebase, time resolution is 1 us (32 MHz !SysClk divided by 32). The PWM scale is from 0 (0 % duty cycle) to 1000 (100 % duty cycle), this results in a PWM frequency of 1 kHz. If you need higher PWM frequencies, decrease the divider and/or the scale.

PWM port pins: D0 (!TIM1CH3), D1 (!TIM1CH2), A4 (!TIM1CH1) 

Simple test program to set brightness of a LED on pin A4 with a potentiometer on A0. Default PWM frequency is 1 kHz (prescaler set to 32). You can set the prescale with the word =pwmprescale= from 32 kHz (value 1) down to 0.5 Hz (64000).
<pre>
5 20 dmod   \ set A4 to PWM

: pwm ( -- )
  begin 
    0 apin@  4 /  20 pwmpin!
    10 osDelay drop
    switch1? 
  until 
;
</pre>

%DASHBOARD{ section="box_end" }%

%DASHBOARD{ section="box_start"  width="992" height="500" }%
---+ Using Input Capture and Output Compare

---++ Time Base

Default timer resolution is 1 us. The 32 bit TIMER2 is used as time base for Input Capture / Output Compare. For a 5 s period 5'000'000 cycles are needed. 
All channels (input capture / output compare) use the same time base.
<pre>
: period ( -- )
  5000000 ICOCperiod! \ 5 s period
  ICOCstart
  begin
     waitperiod
     cr .time
  key? until
  key drop 
;
</pre>


---++ Output Compare

Output compare port pins: D13=13 (!TIM2CH1), A2=18 (!TIM2CH3), A3=19 (!TIM1CH4) 

<pre>
: oc-toggle ( -- )
  5000000 ICOCperiod! \ 5 s period
  ICOCstart
  3 13 OCmod  1000000 13 OCstart \ toggle D13 after 1 s
  3 18 OCmod  2000000 18 OCstart \ toggle A2 after 2 s
  3 19 OCmod  3000000 19 OCstart \ toggle A3 after 3 s 
  begin
     waitperiod
     cr .time
  key? until
  key drop 
;
</pre>

When you abort (hit any key) the program, the timer still runs and controls the port pins. To stop the port pins:
<pre>
13 OCstop  18 OCstop  19 OCstop
</pre>

Or change the prescale to make it faster or slower:
<pre>
1 ICOCprescale
</pre>


---++ Input Capture

Input capture port pin: A1 (!TIM2CH2)

This sample program measures the time between the edges on port A1. if no event occurs within 2 seconds, "timeout" is issued. Hit any key to abort program.
<pre>
: ic-test ( -- )
  6 17 dmod \ input capture on A1
  ICOCstart
  2 ICstart  \ both edges
  ICOCcount@ ( -- count )
  begin
    2000 \ 2 s timeout
    ICwait ( -- old-capture capture ) 
    cr
    dup 0= if
      ." timeout" drop
    else 
      dup rot ( -- capture capture old-capture )
      - 1000 / . ." ms"
    then
  key? until
  key drop
  drop
  ICstop
;

</pre>

%DASHBOARD{ section="box_end" }%

%DASHBOARD{ section="box_start"  width="992" height="400" }%
---+ Using EXTI line

EXTI port pins: D2 (PB5), D3 (PB4), D5 (PB3), D6 (PB2), D7 (PB1)

<pre>
: exti-test ( -- )
  2 2 EXTImod \ both edges on D2
  begin
    2000 2 EXTIwait \ wait for edge on D2 with 2 s timeout
    cr
    0= if
      2 dpin@ if
        ." rising edge"
      else
        ." falling edge"
      then 
    else
      ." timeout"
    then
  key? until
  key drop
;
</pre>

%DASHBOARD{ section="box_end" }%

%DASHBOARD{ section="box_start"  width="992" height="800" }%

---+ Pinout

Very similar to the Teensy 3.0 [[https://www.pjrc.com/teensy/pinout.html][pinout]]. 

<img src="%PUBURLPATH%/MecrispCube/MecrispCubeWB/firefly-pins.jpg" alt="firefly-pins.jpg" width="950"  />

   * Firefly https://www.tindie.com/products/tleracorp/firefly-ble-development-board/
   * Katydid https://www.tindie.com/products/tleracorp/katydid-wearable-ble-sensor-board 

%IMAGE{"%PUBURLPATH%/MecrispCube/MecrispCubeWB/firefly-pins.jpg" type="thumb" caption=""}%

%PUBURLPATH%/MecrispCube/MecrispCubeWB/firefly-pins.jpg

---++ JTAG/SWD

| *JTAG Pin*  | *JTAG STM 14pin* | *JP3 Firefly*  | *JP7 Firefly* | *Description*  |
|             | 1                |                |               | NC             |
|             | 2                |                |               | NC             |
| 1           | 3                | 3              |               | 3V3 VDD        |
| 2           | 4                | 5              |               | SWDIO          |
| 3           | 5                | 2              |               | GND            |
| 4           | 6                | 6              |               | SWCLK          |
| 5           | 7                | 2              |               | GND            |
| 6           | 8                |                |               | SWO            |
| 7           | 9                |                |               | NC             |
| 8           | 10               |                |               | NC             |
| 9           | 11               | 2              |               | GND_DETECT     |
| 10          | 12               | 4              |               | NRST           |
|             | 13               |                | 5 (PA10)      | D0 UART_TX     |
|             | 14               |                | 4 (PA9)       | D1 UART_RX     |
---++ !STM32WB Firefly Board




 
---+++ Push Button1

| *Signal name* | *STM32WB55 pin*  | *Comment*                  |
| SWITCH1       | PC12             | WKUP3                      |


---+++ LED

| *Signal name* | *STM32WB55 pin*  | *Comment*                  |
| LD1           | PB5              |                            |
| Neopixel      | PC12             | D8                         |


---+++ UART 

| *Signal name* | *Firefly pin*    | *Comment*                  |
| UART_TX       | PB6              | USART1_TX                  |
| UART_RX       | PB7              | USART1_RX                  |



%DASHBOARD{ section="box_end" }%

%DASHBOARD{ section="dashboard_end" }%


-- %USERSIG{PeterSchmid - 2020-04-11}%

<a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-sa/4.0/88x31.png" /></a><br />This work by <a xmlns:cc="http://creativecommons.org/ns#" href="http://spyr.ch" property="cc:attributionName" rel="cc:attributionURL">Peter Schmid</a> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/">Creative Commons Attribution-ShareAlike 4.0 International License</a>.
Attachments
Topic attachments
I	Attachment	History	Action	Size	Date	Who	Comment
png	TEK0012.png	r1	manage	3.6 K	2020-04-16 - 14:22	PeterSchmid
This topic: MecrispCube > WebHome > BoardSupportPackageFirefly
Topic revision: r42 - 2022-10-24 - PeterSchmid