Add native-blink example

.github/workflows/examples.yml

@@ -16,6 +16,7 @@ jobs:
           - "examples/spl-blink"
           - "examples/spl-flash"
           - "examples/spl-uart"
+          - "examples/native-blink"
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v2

appveyor.yml

@@ -8,6 +8,7 @@ environment:
     - PLATFORMIO_PROJECT_DIR: "examples/spl-blink"
     - PLATFORMIO_PROJECT_DIR: "examples/spl-flash"
     - PLATFORMIO_PROJECT_DIR: "examples/spl-uart"
+    - PLATFORMIO_PROJECT_DIR: "examples/native-blink"
 
 install:
   - cmd: git submodule update --init --recursive

examples/native-blink/.gitignore

@@ -0,0 +1 @@
+.pio

examples/native-blink/README.rst

@@ -0,0 +1,54 @@
+..  Copyright 2021-present PlatformIO <contact@platformio.org>
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+       http://www.apache.org/licenses/LICENSE-2.0
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+
+How to build PlatformIO based project
+=====================================
+
+1. `Install PlatformIO Core <http://docs.platformio.org/page/core.html>`_
+2. Download `development platform with examples <https://github.com/platformio/platform-ststm8/archive/develop.zip>`_
+3. Extract ZIP archive
+4. Run these commands:
+
+.. code-block:: bash
+
+    # Change directory to example
+    > cd platform-ststm8/examples/native-blink
+
+    # Build project
+    > platformio run
+
+    # Upload firmware
+    > platformio run --target upload
+
+    # Build specific environment
+    > platformio run -e stm8sblue
+
+    # Upload firmware for the specific environment
+    > platformio run -e stm8sblue --target upload
+
+    # Clean build files
+    > platformio run --target clean
+
+Project description
+===================
+
+This is a baremetal project targeting three STM8S example chips / boards : 
+* STM8S103F3 breakout board 
+* Nucleo-8S207K8
+* Nucleo-8S208RB
+
+The pinmapping is such that the built-in LED of those boards is automatically used.
+
+The project does not any framework like Arduino or SPL for compilation, hence no `framework = ..` line in the `platformio.ini`. Only one `.c` file and the right `.h` device header file is used.
+
+The project uses the FOSS header files from https://github.com/gicking/STM8_headers, which are placed under the MIT license. 
+
+If you wish to adapt this example for more chips and boards, add a new environment for your chip, find the appropriate header file from the referenced repository and include that header.

examples/native-blink/include/README

@@ -0,0 +1,39 @@
+
+This directory is intended for project header files.
+
+A header file is a file containing C declarations and macro definitions
+to be shared between several project source files. You request the use of a
+header file in your project source file (C, C++, etc) located in `src` folder
+by including it, with the C preprocessing directive `#include'.
+
+```src/main.c
+
+#include "header.h"
+
+int main (void)
+{
+ ...
+}
+```
+
+Including a header file produces the same results as copying the header file
+into each source file that needs it. Such copying would be time-consuming
+and error-prone. With a header file, the related declarations appear
+in only one place. If they need to be changed, they can be changed in one
+place, and programs that include the header file will automatically use the
+new version when next recompiled. The header file eliminates the labor of
+finding and changing all the copies as well as the risk that a failure to
+find one copy will result in inconsistencies within a program.
+
+In C, the usual convention is to give header files names that end with `.h'.
+It is most portable to use only letters, digits, dashes, and underscores in
+header file names, and at most one dot.
+
+Read more about using header files in official GCC documentation:
+
+* Include Syntax
+* Include Operation
+* Once-Only Headers
+* Computed Includes
+
+https://gcc.gnu.org/onlinedocs/cpp/Header-Files.html

examples/native-blink/lib/README

@@ -0,0 +1,46 @@
+
+This directory is intended for project specific (private) libraries.
+PlatformIO will compile them to static libraries and link into executable file.
+
+The source code of each library should be placed in a an own separate directory
+("lib/your_library_name/[here are source files]").
+
+For example, see a structure of the following two libraries `Foo` and `Bar`:
+
+|--lib
+|  |
+|  |--Bar
+|  |  |--docs
+|  |  |--examples
+|  |  |--src
+|  |     |- Bar.c
+|  |     |- Bar.h
+|  |  |- library.json (optional, custom build options, etc) https://docs.platformio.org/page/librarymanager/config.html
+|  |
+|  |--Foo
+|  |  |- Foo.c
+|  |  |- Foo.h
+|  |
+|  |- README --> THIS FILE
+|
+|- platformio.ini
+|--src
+   |- main.c
+
+and a contents of `src/main.c`:
+```
+#include <Foo.h>
+#include <Bar.h>
+
+int main (void)
+{
+  ...
+}
+
+```
+
+PlatformIO Library Dependency Finder will find automatically dependent
+libraries scanning project source files.
+
+More information about PlatformIO Library Dependency Finder
+- https://docs.platformio.org/page/librarymanager/ldf.html

examples/native-blink/platformio.ini

@@ -0,0 +1,27 @@
+; PlatformIO Project Configuration File
+;
+;   Build options: build flags, source filter
+;   Upload options: custom upload port, speed and extra flags
+;   Library options: dependencies, extra library storages
+;   Advanced options: extra scripting
+;
+; Please visit documentation for the other options and examples
+; https://docs.platformio.org/page/projectconf.html
+
+[env]
+; baremetal STM8 device headers library
+lib_deps =
+   https://github.com/gicking/STM8_headers/archive/refs/heads/master.zip
+
+[env:stm8sblue]
+platform = ststm8
+board = stm8sblue
+upload_protocol = stlinkv2
+
+[env:nucleo_8s207k8]
+platform = ststm8
+board = nucleo_8s207k8
+
+[env:nucleo_8s208rb]
+platform = ststm8
+board = nucleo_8s208rb

examples/native-blink/src/main.c

@@ -0,0 +1,115 @@
+/**********************
+  Simple blink project w/o interrupts
+
+  supported hardware:
+    - STM8S Discovery board (https://www.st.com/en/evaluation-tools/stm8s-discovery.html)
+    - NUCLEO-8S207K8 (https://www.st.com/en/evaluation-tools/nucleo-8s207k8.html)
+    - NUCLEO-8S208RB (https://www.st.com/en/evaluation-tools/nucleo-8s208rb.html)
+    - STM8L Discovery board (https://www.st.com/en/evaluation-tools/stm8l-discovery.html)
+    - STM8-SO8 Discovery board (https://www.st.com/en/evaluation-tools/stm8-so8-disco.html)
+    - Sduino Uno (https://github.com/roybaer/sduino_uno)
+    - muBoard (http://www.cream-tea.de/presentations/160305_PiAndMore.pdf)
+
+  Functionality:
+    - blink LED w/o ISR. Mainly for testing toolchain
+    - pass port structure to function
+**********************/
+
+/*----------------------------------------------------------
+    SELECT BOARD
+----------------------------------------------------------*/
+//Not needed for PlatformIO since the board definition file
+//automatically activates macros by which we can identify it,
+//like STM8S_NUCLEO_207K8 etc.
+
+//#define STM8S_DISCOVERY
+//#define NUCLEO_8S207K8
+//#define NUCLEO_8S208RB
+//#define STM8L_DISCOVERY
+//#define STM8_SO8_DISCO_STM8S001
+//#define SDUINO
+//#define MUBOARD
+
+/*----------------------------------------------------------
+    INCLUDE FILES
+----------------------------------------------------------*/
+#if defined(STM8S_DISCOVERY)
+  #include "STM8S105C6.h"
+  #define LED_PORT   sfr_PORTD
+  #define LED_PIN    PIN0
+  //print this out as an info during compilation
+  #warning "[INFO] USING STM8S_DISCOVERY PIN MAP"
+#elif defined(STM8S_NUCLEO_207K8)
+  #include "STM8S207K8.h"
+  #define LED_PORT   sfr_PORTC
+  #define LED_PIN    PIN5
+  //print this out as an info during compilation
+  #warning "[INFO] USING NUCLEO_8S207K8 PIN MAP PORTC PIN5"
+#elif defined(STM8S_NUCLEO_208RB)
+  #include "STM8S208RB.h"
+  #define LED_PORT   sfr_PORTC
+  #define LED_PIN    PIN5
+  //print this out as an info during compilation
+  #warning "[INFO] USING NUCLEO_8S208RB PIN MAP PORTC PIN5"
+#elif defined(STM8L_DISCOVERY)
+  #include "STM8L152C6.h"
+  #define LED_PORT   sfr_PORTC
+  #define LED_PIN    PIN7
+#elif defined(STM8_SO8_DISCO_STM8S001)
+  #include "STM8S001J3.h"
+  #define LED_PORT   sfr_PORTA
+  #define LED_PIN    PIN3
+#elif defined(SDUINO)
+  #include "STM8S105K6.h"
+  #define LED_PORT   sfr_PORTC
+  #define LED_PIN    PIN5
+#elif defined(MUBOARD)
+  #include "STM8S207MB.h"
+  #define LED_PORT   sfr_PORTH
+  #define LED_PIN    PIN2
+#else
+  #include "STM8S103F3.h"
+  #define LED_PORT   sfr_PORTB
+  #define LED_PIN    PIN5
+  #warning "[INFO] USING STM8S103F3 PINMAP PORTB, PIN 5"
+#endif
+
+// toggle specified pin. Pass port struct as pointer
+void toggle_pin(PORT_t *port, uint8_t pin) {
+
+  port->ODR.byte ^= pin;
+
+} // toggle_pin
+
+/////////////////
+//    main routine
+/////////////////
+void main (void) {
+
+  uint32_t  i = 0;
+
+  // switch to 16MHz (default is 2MHz)
+  sfr_CLK.CKDIVR.byte = 0x00;
+
+  // configure LED pin as output
+  LED_PORT.DDR.byte = LED_PIN;    // input(=0) or output(=1)
+  LED_PORT.CR1.byte = LED_PIN;    // input: 0=float, 1=pull-up; output: 0=open-drain, 1=push-pull
+  LED_PORT.CR2.byte = LED_PIN;    // input: 0=no exint, 1=exint; output: 0=2MHz slope, 1=10MHz slope
+
+  // main loop
+  while(1) {
+
+    // toggle LED. Pass port struct as pointer
+    toggle_pin(&LED_PORT, LED_PIN);
+
+    // simple wait ~500ms @ 16MHz
+    for (i=0; i<300000L; i++)
+      NOP();
+
+  } // main loop
+
+} // main
+
+/*-----------------------------------------------------------------------------
+    END OF MODULE
+-----------------------------------------------------------------------------*/

examples/native-blink/test/README

@@ -0,0 +1,11 @@
+
+This directory is intended for PlatformIO Unit Testing and project tests.
+
+Unit Testing is a software testing method by which individual units of
+source code, sets of one or more MCU program modules together with associated
+control data, usage procedures, and operating procedures, are tested to
+determine whether they are fit for use. Unit testing finds problems early
+in the development cycle.
+
+More information about PlatformIO Unit Testing:
+- https://docs.platformio.org/page/plus/unit-testing.html