sduino/index.html at gh-pages · spreadspace/sduino

666 lines (538 loc) · 23.8 KB
<!DOCTYPE html>
<html lang="en">
        <meta charset="utf-8">
        <meta http-equiv="X-UA-Compatible" content="IE=edge">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <link rel="shortcut icon" href="./img/favicon.ico">
	<title>Sduino</title>
        <link href="./css/bootstrap-custom.min.css" rel="stylesheet">
        <link href="./css/font-awesome-4.0.3.css" rel="stylesheet">
        <link href="./css/base.css" rel="stylesheet">
        <link rel="stylesheet" href="./css/highlight.css">
        <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
        <!--[if lt IE 9]>
            <script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
            <script src="https://oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
        <![endif]-->
    </head>
    <body class="homepage">
        <div class="navbar navbar-default navbar-fixed-top" role="navigation">
    <div class="container">
        <!-- Collapsed navigation -->
        <div class="navbar-header">
            <!-- Expander button -->
            <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
                <span class="sr-only">Toggle navigation</span>
                <span class="icon-bar"></span>
                <span class="icon-bar"></span>
                <span class="icon-bar"></span>
            </button>
            <!-- Main title -->
            <a class="navbar-brand" href=".">Sduino</a>
        </div>
        <!-- Expanded navigation -->
        <div class="navbar-collapse collapse">
                <!-- Main navigation -->
                <ul class="nav navbar-nav">
                    <li class="dropdown active">
                        <a href="#" class="dropdown-toggle" data-toggle="dropdown">User Guide <b class="caret"></b></a>
                        <ul class="dropdown-menu">
<li class="active">
    <a href=".">Overview</a>
    <a href="install/">Installation</a>
    <a href="sdcc/">Using the SDCC compiler</a>
    <a href="spl/">Using the SPL with SDCC and sduino</a>
    <a href="macro/">C preprocessor macro magic</a>
                    <li class="dropdown">
                        <a href="#" class="dropdown-toggle" data-toggle="dropdown">Libraries <b class="caret"></b></a>
                        <ul class="dropdown-menu">
    <a href="api/">API description and migration guidelines</a>
    <a href="api/HardwareSerial/">HardwareSerial</a>
    <a href="api/SPI/">SPI</a>
    <a href="api/I2C/">I2C</a>
    <a href="api/LiquidCrystal/">LiquidCrystal character LCD library</a>
    <a href="api/PCD8544/">PCD8544 libray for Nokia 5110-like graphical LCDs</a>
    <a href="api/Mini_SSD1306/">Mini_SSD1306 library for monochrome OLED-displays</a>
    <a href="api/Stepper/">Stepper library</a>
    <a href="api/Servo/">Servo library</a>
                    <li class="dropdown">
                        <a href="#" class="dropdown-toggle" data-toggle="dropdown">Hardware <b class="caret"></b></a>
                        <ul class="dropdown-menu">
    <a href="hardware/flashtool/">Flash tool</a>
    <a href="hardware/">List of supported boards</a>
    <a href="pin_mapping/">Ways to define a pin mapping</a>
    <a href="hardware/stm8blue/">Generic STM8S103 breakout board (stm8blue)</a>
    <a href="hardware/esp14/">ESP14: Wifi board, STM8S003</a>
    <a href="hardware/stm8sdiscovery/">STM8S105Discovery: Evaluation board made my ST</a>
                        <a href="about/">About</a>
                </ul>
            <ul class="nav navbar-nav navbar-right">
                    <a href="#" data-toggle="modal" data-target="#mkdocs_search_modal">
                        <i class="fa fa-search"></i> Search
                </li>
                    <li class="disabled">
                        <a rel="next" >
                            <i class="fa fa-arrow-left"></i> Previous
                        <a rel="prev" href="install/">
                            Next <i class="fa fa-arrow-right"></i>
            </ul>
        </div>
        <div class="container">
                <div class="col-md-3"><div class="bs-sidebar hidden-print affix well" role="complementary">
    <ul class="nav bs-sidenav">
        <li class="main active"><a href="#sduino">Sduino</a></li>
            <li><a href="#usage">Usage</a></li>
            <li><a href="#tools-used">Tools used</a></li>
            <li><a href="#supported-hardware">Supported hardware</a></li>
            <li><a href="#compatibility-with-the-arduino-world">Compatibility with the Arduino world</a></li>
            <li><a href="#included-libraries">Included libraries</a></li>
            <li><a href="#float-arithmetics">Float arithmetics</a></li>
            <li><a href="#current-status-and-to-do-list">Current status and to-do list</a></li>
            <li><a href="#why-use-a-stm8-instead-of-an-atmega">Why use a STM8 instead of an ATmega?</a></li>
            <li><a href="#further-reading-and-application-notes">Further reading and application notes</a></li>
            <li><a href="#modifications-for-the-sdcc-example-programs">Modifications for the sdcc example programs</a></li>
</div></div>
                <div class="col-md-9" role="main">
<h1 id="sduino">Sduino</h1>
<p>Porting the most important features of the Arduino API to the STM8S.</p>
<p>Within a few minutes you are ready to compile and upload your first
STM8S-based project while still retaining the flexibility to use ST's SPL
functions.</p>
<p>All you need to get started is a simple STM8S103F breakout board for 70
cents and a ST-Link V2 compatible flash programmer for $2.50. Three boards
and one flash programmer together are available for well under five dollars
including shipping on <a href="http://www.aliexpress.com/">aliexpress</a>.</p>
<p><em>Amazing!</em></p>
<h2 id="usage">Usage</h2>
<p>If you have ever used the Arduino environment before you will feel at home
right away, despite this project beeing based on a makefile rather than the
full Arduino IDE. But don't be afraid, it is based on the amazing
<a href="https://github.com/sudar/Arduino-Makefile">Arduino.mk makefile</a> by
<a href="http://sudarmuthu.com&gt;">Sudar</a> to control the build process, that makes
everything very easy.</p>
<p>Let's blink an LED using the Blink example from Arduino:</p>
<pre><code class="c">/*
  Turns on an LED on for one second, then off for one second, repeatedly.
  This example code is in the public domain.
#include &lt;Arduino.h&gt;
// Pin 13 has an LED connected on most Arduino boards.
// Pin 3 for the STM8S103 break out board
// give it a name:
int led = LED_BUILDIN;
// the setup routine runs once when you press reset:
void setup() {
  // initialize the digital pin as an output.
  pinMode(led, OUTPUT);
// the loop routine runs over and over again forever:
void loop() {
  digitalWrite(led, HIGH);   // turn the LED on (HIGH is the voltage level)
  delay(1000);               // wait for a second
  digitalWrite(led, LOW);    // turn the LED off by making the voltage LOW
  delay(1000);               // wait for a second
</code></pre>
<p>All we need for a full build is this very basic <code>Makefile</code>:</p>
<pre><code class="make">BOARD_TAG   = stm8sblue
include ../../sduino/sduino.mk
</code></pre>
<p>Compile and upload it:</p>
<pre><code>make upload
</code></pre>
<p>Done! Your first STM8 based project is up and running!</p>
<h2 id="tools-used">Tools used</h2>
<p>This project is based on free tools that are available for Linux, MacOS, and
Windows. <a href="install/">Installation instructions</a></p>
<p>It uses the small devices C compiler (SDCC) for compiling,
<a href="https://github.com/vdudouyt/stm8flash">stm8flash</a> for uploading the binary
to the CPU, and simple Makefiles for the build process.</p>
<p><a href="sdcc/">More information on using SDCC</a></p>
<p>Support for the Cosmic compiler under Windows and integration into the ST
visual developer IDE might be possible, but is not done (yet?).</p>
<p>The build process is controlled by a makefile based on the amazing
<a href="https://github.com/sudar/Arduino-Makefile">Arduino.mk makefile</a> by
<a href="http://sudarmuthu.com&gt;">Sudar</a>.</p>
<h2 id="supported-hardware">Supported hardware</h2>
<p>The <a href="hardware/stm8blue/">one-dollar-boards</a>: A simple STM8S103 breakout
  board build around a CPU STM8S103F3P6. It costs less than a dollar. The
  CPU features a 16MHz internal oscillator, 8kB flash, 1kB RAM, 640 byte
  EEPROM. It includes an UART, SPI, I2C, PWM, 10 bit ADC, 3 timer, and up to
  14 I/O pins - quite similar to an Atmel ATmega8.</p>
<p>The <a href="hardware/esp14/">ESP14 Wifi-boards</a> are very similar. They are
  basically a variant of these boards with an added ESP-01 Wifi-module. Almost
  all programs should run on those chinese Wifi-enabled gems as well.</p>
<p>The <a href="hardware/stm8sdiscovery/">STM8S105Discovery-boards</a> are very similar
  to an Arduino Uno with an ATmega328 CPU. The support for the used STM8S105
  CPU is still quite fresh but it should work now.</p>
<h2 id="compatibility-with-the-arduino-world">Compatibility with the Arduino world</h2>
<p>I adopted the Arduino core functionality for the STM8S to set up a simple
programming environment. But unfortunatly there is no free C++ compiler
for these CPUs. This makes it impossible to do a full port of the whole
enviroment and integrate it with the Arduino IDE and build system as is
has been done for the STM32 and the ESP8266.</p>
<p>This is not a drop-in replacement for an AVR, but the programming API is
still very, very similar. Adopting existing libraries from C++ to C for use
with the simplified C API is often easy and can be done quite fast,
depending on the degree of dependency on specific hardware features.</p>
<p>The whole Arduino build system is deeply based on the assumption of
processing C++ source files. I am not sure if it would be even possible to
configure a build process based only on C files without modifing the IDE
sources. This makes a full IDE integration very unlikely.</p>
<p>Using a converter/compiler like
<a href="https://en.wikipedia.org/wiki/Cfront">cfront</a> to translate from C++ to C
might be an option.</p>
<h2 id="included-libraries">Included libraries</h2>
<p>Some Arduino libraries are already ported to C-syntax. The resulting API is
still very close to the C++ version and porting an existing application is
not hard. Check out the <a href="api/">API migration guidelines</a> for details.</p>
<h4 id="communication">Communication</h4>
<li><a href="api/SPI/">SPI</a>: Real hardware-SPI up to 10MHz.</li>
<li><a href="api/I2C/">I2C</a>: Port of the I2C master library by Wayne Truchsess</li>
<li>HardwareSerial: The standard serial interface.</li>
<h4 id="displays">Displays</h4>
<li><a href="api/LiquidCrystal/">LiquidCrystal</a>: HD44780 based text LCDs</li>
<li><a href="api/PCD8544/">PCD8544</a>: Monochrome graphical LCD based on the PCD8544
  controller like the Nokia 5110 display. SPI mode only.</li>
<li><a href="api/Mini_SSD1306/">Mini_SSD1306</a>: SSD1306-based monochrome OLED displays
  with 128x64 pixels. I2C support only.</li>
<h4 id="motor-control">Motor control</h4>
<li><a href="api/Stepper/">Stepper</a>: Stepper motors with 2, 4 or 5 phases.</li>
<li><a href="api/Servo/">Servo</a>: Up to 12 servos using only 1 timer.</li>
<h2 id="float-arithmetics">Float arithmetics</h2>
<p>Floating point arithmetics is supported by the SDCC standard library, but it
comes at a pretty high cost in terms of code space and CPU load. This is how
much the generated code grows by using a single float operation compared to 
using a long int:</p>
<th>Floating point operation</th>
<th>approx. code size</th>
<td>addition</td>
<td>736 Bytes</td>
<td>subtraction</td>
<td>754 Bytes</td>
<td>division</td>
<td>673 Bytes</td>
<td>multiplication</td>
<td>907 Bytes</td>
<td>sinf() or cosf()</td>
<td>3346 Bytes</td>
<td>log10f()</td>
<td>3437 Bytes</td>
<p>The Arduino standard example '01. Basics/ReadAnalogVoltage' is a very simple
simple program with only very little floating point arithmetics. But it
already uses 7336 bytes of flash. A similar sketch using integer arithmetics
results in much more compact code occuping only 3791 bytes.</p>
<p>Float does work, but is better to be avoided and replaced by fixed point
arithmetics whenever possible.</p>
<h2 id="current-status-and-to-do-list">Current status and to-do list</h2>
<h4 id="tested-and-working">tested and working</h4>
<p><code>pinMode()</code><br />
<code>digitalWrite()</code><br />
<code>analogRead()</code><br />
<code>delay()</code><br />
<code>analogWrite()</code><br />
<code>ShiftOut()</code><br />
WMath: <code>map()</code><br />
HardwareSerial<br />
Print<br />
<code>pulseInLong()</code><br />
<a href="api/SPI/">SPI</a>:
  working, no interrupt support<br />
<a href="api/LiquidCrystal/">LiquidCrystal</a>:
  Text LCD based on the HD44780 controller<br />
<a href="api/PCD8544/">PCD8544</a>:
  Nokia 5110 type displays<br />
<a href="api/Mini_SSD1306/">Mini_SSD1306</a>:
  Monochrome OLED displays based on the SSD1306 controller
<a href="api/Stepper/">Stepper</a>:
  Multi-instance design for more than one stepper at a time<br />
<a href="api/Servo/">Servo</a>:
  Multi-instance design for more than one servo at a time)  </p>
<h4 id="implemented-and-partly-working">implemented and partly working</h4>
<p>Wire/I2C  </p>
<h4 id="tested-but-not-working">tested, but not working</h4>
<p><code>alternateFunctions()</code>  </p>
<h4 id="not-tested">not tested</h4>
<p><code>ShiftIn()</code><br />
<code>random()</code><br />
<code>srandom()</code>  </p>
<h4 id="not-implemented">not implemented</h4>
<p><code>tone()</code><br />
<code>noTone()</code><br />
<code>pulseIn()</code><br />
module WCharacter<br />
module WString  </p>
<h4 id="unresolved-problems">Unresolved problems</h4>
<p>The compile environment needs to detect which interrupts are actively used
and link only the needed ones into the binary. See test/digitalWrite:
Compiling with the straight Makefile.classic does not add UART interrupt
routines. But when using the sduino.mk Makefile the two UART interrupt
routines are pulled into the binary by the interrupt table in main.c.</p>
<h2 id="why-use-a-stm8-instead-of-an-atmega">Why use a STM8 instead of an ATmega?</h2>
<p>The fairly new ESP-14 module includes a STM8S003F3P6. Wifi and a
programmable I/O-CPU for just over two dollars - that might be the most
compelling reason to get started on the STM8S series. Apart from pure
curiosity and eagerness to learn something new, of course.</p>
<p>The simple STM8S103F breakout boards are powerful and dirt cheap. They cost
well under one dollar. You can get three boards and one flash programmer
together for well under five dollars on http://www.aliexpress.com/ ,
including shipping from China.</p>
<p>The major downside of this CPU series is the lack of information and
community support for the STM8. The community support and the sheer number
of existing libraries for all kinds of sensors and hardware is outstanding
in the Arduino world. If you just want to get something done, go for an
Arduino board. Nothing will give you faster and easier results.</p>
<p>For commercial use the STM8S offers some interesting advantages:</p>
<p><strong>Motor control</strong>: The STM8 has a strong focus on motor and position control
systems. Things you need to handle yourself on an ATmega are implemented in
hardware and work independently of the state of the software. There is even
hardware support for quadrature encoders as used in position sensors and
rotary encoders.</p>
<p><strong>Low power modes</strong>: The numbers in the datasheets don't look that different,
but in real life the STM8 can be powered two or three times longer using the
same battery capacity due to the finer control on the power modes (very,
very careful programming required).</p>
<p><strong>Value for the money</strong>: 40 to 60 cents for a STM8 with 14 I/O pins compared to
$1.60-$3.00 for an ATmega8.</p>
<p><strong>Upgrade path</strong>: The peripheral units of the STM8 are identical or at least
very, very similar to the ones used with the STM32 family of 32 bit
ARM-Cortex CPUs. This makes it is relatively easy to migrate existing
software between the 8- and the 32-bit world. This is quite unique among the
other CPUs.</p>
<h2 id="further-reading-and-application-notes">Further reading and application notes</h2>
<p><a href="https://github.com/tenbaht/sduino/blob/master/docs/index.md">project documentation files</a>
More in detail information about supported boards, tools and the API.</p>
<p>[Quick introduction to the Arduino.mk makefile]
(http://hackaday.com/2015/10/01/arduino-development-theres-a-makefile-for-that/)</p>
<p><a href="http://www.st.com/resource/en/programming_manual/cd00191343.pdf">PM0051</a>:
STM8AF Flash programming manual<br />
<a href="http://www.st.com/resource/en/user_manual/cd00173911.pdf">UM0470</a>:
STM8 SWIM protocol and debug manual<br />
<a href="http://www.st.com/resource/en/application_note/cd00176594.pdf">AN2658</a>:
Using the analog-to-digital converter of the STM8S microcontroller  </p>
<p>Many examples and presentations about the STM8S:<br />
https://github.com/VincentYChen/STM8teach<br />
It contains the SPL examples from ST, the most useful resource on the STM8:<br />
https://github.com/VincentYChen/STM8teach/tree/master/code/Project/STM8S_StdPeriph_Examples</p>
<p>Hardware and pinouts of several ST-Link compatible flash tools:
https://wiki.cuvoodoo.info/doku.php?id=jtag</p>
<p>Using the ADC:<br />
http://blog.mark-stevens.co.uk/2012/09/single-scan-adc-on-the-stm8s/  </p>
<p>Example for RS-232 handling with SPL:<br />
https://sourceforge.net/p/oggstreamer/oggs-stm8-firmware-001/ci/master/tree/rx_ringbuffer.c  </p>
<p><a href="http://www.st.com/resource/en/application_note/cd00262293.pdf">AN3139</a>:
Migration guideline within the STM8L familiy  </p>
<h2 id="modifications-for-the-sdcc-example-programs">Modifications for the sdcc example programs</h2>
<p>blinky.c: LED pin assignment</p>
<p><strong>uart.c</strong>:  pin assignment (TX is at PD5, RX is at PD6).<br />
The UART is sending at 1200 Baud =&gt; CPU clock only 2MHz instead of 16MHz.
The clock divider needs to be configured or a different baud rate prescale value
has to be used. Pitfall: The register address for the clock divider is
different for the STM8S and the STM8L.</p>
<h3 id="performance-compared-with-the-original-arduino-environment">Performance compared with the original Arduino environment</h3>
<p>Benchmarking the original Arduino examples from Arduino 1.0.5. The simple
Blinky compiles to 57 bytes of code, the total binary including the sduino
libraries is 1868 Bytes (0x74c).</p>
<p>So far, wiring_analog depends on wiring_digital, even when analogWrite is not
used. This could be solved by compiling the sduino functions separately into
a library.</p>
<th>Name</th>
<th>Code</th>
<th>Total</th>
<th>Linked files other than main and wiring</th>
<td>01. Basics/</td>
<td>BareMinimum</td>
<td>1238</td>
<td>Blink</td>
<td>57</td>
<td>1870</td>
<td>wiring_digital</td>
<td>AnalogReadSerial</td>
<td>205</td>
<td>3452</td>
<td>digital, analog, serial, print</td>
<td>DigitalReadSerial</td>
<td>57</td>
<td>3160</td>
<td>digital, serial, print</td>
<td>Fade</td>
<td>226</td>
<td>2189</td>
<td>digital, analog</td>
<td>ReadAnalogVoltage</td>
<td>float not yet implemented</td>
<td>02. Digital/</td>
<td>Debounce</td>
<td>192</td>
<td>2016</td>
<td>digital</td>
</table></div>
        </div>
        <footer class="col-md-12">
            <hr>
            <p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</p>
        </footer>
        <script src="./js/jquery-1.10.2.min.js"></script>
        <script src="./js/bootstrap-3.0.3.min.js"></script>
        <script src="./js/highlight.pack.js"></script>
        <script>var base_url = '.';</script>
        <script data-main="./mkdocs/js/search.js" src="./mkdocs/js/require.js"></script>
        <script src="./js/base.js"></script>
        <div class="modal" id="mkdocs_search_modal" tabindex="-1" role="dialog" aria-labelledby="Search Modal" aria-hidden="true">
            <div class="modal-dialog">
                <div class="modal-content">
                    <div class="modal-header">
                        <button type="button" class="close" data-dismiss="modal"><span aria-hidden="true">&times;</span><span class="sr-only">Close</span></button>
                        <h4 class="modal-title" id="exampleModalLabel">Search</h4>
                    </div>
                    <div class="modal-body">
                            From here you can search these documents. Enter
                            your search terms below.
                        <form role="form">
                            <div class="form-group">
                                <input type="text" class="form-control" placeholder="Search..." id="mkdocs-search-query">
                        </form>
                        <div id="mkdocs-search-results"></div>
                    </div>
                    <div class="modal-footer">
                    </div>
                </div>
            </div>
        </div>
    </body>
MkDocs version : 0.14.0
Build Date UTC : 2017-04-24 10:51:30.802305
Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FilesExpand file tree

index.html

Latest commit

History

index.html

File metadata and controls
