Skip to content

Commit 5c3d253

Browse files
tenbahttenbaht
committed
rewrite the README
1 parent 651e46a commit 5c3d253

2 files changed

Lines changed: 107 additions & 187 deletions

File tree

‎README.md‎

Lines changed: 57 additions & 160 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,37 @@
1-
# sduino
1+
## Sduino: Small Devices Arduino
22

33
Getting started on the STM8 CPU the easy way by using an Arduino-like
44
programming API.
55

66
This project makes the most important features of the Arduino API available
7-
for the STM8S. It is based on free tools that are available for Linux, MacOS, and
8-
Windows.
7+
for the STM8S. It is based on free tools that are available for Linux,
8+
MacOS, and Windows: SDCC, make, and stm8flash.
9+
10+
Since it's based on the SDCC Small Devices compiler, I called it "Small
11+
Devices -uino" or "Small-duino".
12+
13+
This project is not supposed to be “better than Arduino”. It’s purpose
14+
is to give you a head start into a different CPU architecture if you happen
15+
to have a professional need or a private desire for it.
916

1017
Please find more detailed information about the supported boards, the needed tools
1118
and the library APIs on the
1219
[project documentation files](https://github.com/tenbaht/sduino/blob/master/docs/index.md).
1320

1421

15-
16-
1722
## Table of Contents
1823

1924
* [Project Website](blob/master/docs/index.md)
2025
* [Usage example](#usage)
21-
* [Installation](#installation)
2226
* [Supported hardware](#supported-hardware)
2327
* [Why use a STM8 instead of an ATmega?](#why-use-a-stm8-instead-of-an-atmega)
28+
* [Library support](#library-support)
2429
* [Compatibility with the Arduino world](#compatibility-with-the-arduino-world)
25-
* [Current status and to-do list](#current-status-and-to-do-list)
26-
* [Further reading and application notes](#further-reading-and-application-notes)
2730

2831

2932

30-
## Usage
33+
34+
## Usage example
3135

3236
If you have ever used the Arduino environment before you will feel at home
3337
right away, despite this project beeing based on a makefile rather than the
@@ -36,7 +40,7 @@ full Arduino IDE. But don't be afraid, it is based on the amazing
3640
[Sudar](http://sudarmuthu.com>) to control the build process, that makes
3741
everything very easy.
3842

39-
Let's blink an LED using the Blink example from Arduino:
43+
First, let's make an LED blink using the Blink example from Arduino:
4044

4145
```c
4246
/*
@@ -83,56 +87,32 @@ Compile and upload it:
8387
Done! Your first STM8 based project is up and running!
8488

8589

86-
87-
88-
## Installation
89-
90-
This project uses the small devices C compiler (SDCC) for compiling,
91-
[stm8flash](https://github.com/vdudouyt/stm8flash) for uploading the binary
92-
to the CPU, and simple Makefiles for the build process. Support for the
93-
Cosmic compiler under Windows and integration into the ST visual developer
94-
IDE might be possible, but is not done (yet?).
95-
96-
This is a quick overview for the installation on a Linux system. Check the
97-
[installation instructions](https://github.com/tenbaht/sduino/blob/master/docs/install.md)
98-
for other systems.
99-
100-
101-
Download and extract the
102-
[lastest snapshot build for SDCC](http://sdcc.sourceforge.net/snap.php) to
103-
`/opt`:
104-
105-
sudo mkdir /opt
106-
sudo tar xvjf ~/Downloads/sdcc-snapshot* -C /opt
107-
108-
Make sure make is available:
109-
110-
sudo apt-get install make
111-
112-
Download/clone this repository somewhere convinient (but separate from your
113-
existing Arduino files, at least for now):
114-
115-
git clone [email protected]:tenbaht/sduino.git
116-
117-
compile an example sketch:
118-
119-
cd sduino/sduino/examples/01.Basics/Blink
120-
make
121-
122-
123-
More details and instructions for MacOS and Windows in the
124-
[installation instructions](https://github.com/tenbaht/sduino/blob/master/docs/install.md).
125-
126-
127-
128-
12990
## Supported hardware
13091

131-
[STM8S103 breakout board](blob/master/docs/hardware/stm8blue.md):
132-
works.
133-
[ESP14 Wifi board](blob/master/docs/hardware/esp14.md): works.
134-
[STM8S105 Discovery board](blob/master/docs/hardware/stm8disco.md):
135-
not supported yet, but work in progress.
92+
Anything with an STM8S103 or STM8S003 should work. For example, the
93+
70-cent-[STM8S103 breakout boards](blob/master/docs/hardware/stm8blue.md),
94+
[ESP14 Wifi boards](blob/master/docs/hardware/esp14.md),
95+
or even the [W1209 thermostat boards](https://www.aliexpress.com/wholesale?SearchText=w1209)
96+
that are abundant on aliexpress and Amazon. All you need to get started is a
97+
simple ST-Link/V2 compatible flash programmer, available for less then $3
98+
from China.
99+
100+
The STM8 series by ST might be the cheapest CPUs on the market while still
101+
being as powerful as the ATmega series. That makes them every Chinese
102+
engineer's darling and chances are pretty good that you will find an '003 if
103+
you crack open any cheap appliance like an irrigation, temperature, or
104+
charging controller.
105+
106+
The '003 or '103 CPUs feature a 16MHz internal oscillator, 8kB flash, 1kB
107+
RAM and 128 or 640 byte EEPROM. They both include a UART, SPI, I2C, PWM,
108+
five 10 bit ADC inputs, 3 timers, and up to 14 I/O pins - quite similar to
109+
an Atmel ATmega8 as it was used on the first Arduino boards.
110+
111+
Support for the more powerful
112+
[STM8S105 Discovery board](blob/master/docs/hardware/stm8disco.md)
113+
is planned, but not available yet. These amazing $9 boards offer even more
114+
resources, come with a build-in flash programmer and are very similar to an
115+
Arduino Uno with an ATmega328 CPU.
136116

137117
Find more information here: [Supported Boards](blob/master/docs/hardware.md)
138118

@@ -150,8 +130,6 @@ well under one dollar. You can get three boards and one flash programmer
150130
together for well under five dollars on http://www.aliexpress.com/ ,
151131
including shipping from China.
152132

153-
*Amazing!*
154-
155133
The major downside is the lack of information and community support for the
156134
STM8. The community support and the sheer number of existing libraries for
157135
all kinds of sensors and hardware is outstanding in the Arduino world. If
@@ -182,120 +160,39 @@ other CPUs.
182160

183161

184162

163+
## Library support
164+
165+
The most important libraries and parts of the Arduino core system are
166+
ported for the STM8 already: analog input and output, digital input and
167+
output, delay(), millis(), Serial, SPI, and I2C.
168+
169+
There are ported versions of the standard libraries Servo, Stepper, and
170+
LiquidCrystal for motor control and the popular text LCDs based on the
171+
HD44780 controller.
172+
173+
For more sophisticated output there are libraries for Nokia-5110-type
174+
graphical LCDs and SSD1306-based graphical OLED displays.
175+
176+
177+
185178
## Compatibility with the Arduino world
186179

187180
I adopted the Arduino core functionality for the STM8S to set up a simple
188181
programming environment. But unfortunatly there is no free C++ compiler
189182
for these CPUs. This makes it impossible to do a full port of the whole
190-
enviroment and integrate it with the Arduino IDE and build system as is
183+
enviroment and integrate it with the Arduino IDE and build system as it
191184
has been done for the STM32 and the ESP8266.
192185

193186
This is not a drop-in replacement for an AVR, but the programming API is
194-
still very, very similar. Adopting existing libraries from C++ to C for use
195-
with the simplified C API is often easy and can be done quite fast,
196-
depending on the degree of dependency on specific hardware features.
187+
still very, very similar. Thanks to some C preprocessor magic it is often
188+
enough to just move over the opening bracket of the class instanciation
189+
statement and to replace the dot in a method call for an underscore.
197190

198191
The whole Arduino build system is deeply based on the assumption of
199192
processing C++ source files. I am not sure if it would be even possible to
200193
configure a build process based only on C files without modifing the IDE
201194
sources. This makes a full IDE integration very unlikely.
202195

203-
Using a converter/compiler like
204-
[cfront](https://en.wikipedia.org/wiki/Cfront) to translate from C++ to C
205-
might be an option.
206-
207-
208-
209-
## Current status and to-do list
210-
211-
#### tested and working
212-
`pinMode()`
213-
`digitalWrite()`
214-
`analogRead()`
215-
`delay()`
216-
`analogWrite()`
217-
`ShiftOut()`
218-
WMath: `map()`
219-
[HardwareSerial]
220-
Print (without float)
221-
[SPI](https://github.com/tenbaht/sduino/blob/master/docs/SPI.md):
222-
working, no interrupt support
223-
[LiquidCrystal](https://github.com/tenbaht/sduino/blob/master/docs/api/LiquidCrystal.md):
224-
Text LCD based on the HD44780 controller
225-
[PCD8544](https://github.com/tenbaht/sduino/blob/master/docs/api/PCD8544.md):
226-
Nokia 5110 type displays
227-
[Mini_SSD1306](https://github.com/tenbaht/sduino/blob/master/docs/api/Mini_SSD1306.md):
228-
Monochrome OLED displays based on the SSD1306 controller
229-
[Stepper](https://github.com/tenbaht/sduino/blob/master/docs/api/Stepper.md):
230-
Multi-instance design for more than one stepper at a time
231-
[Servo](https://github.com/tenbaht/sduino/blob/master/docs/api/Servo.md):
232-
Multi-instance design for more than one servo at a time)
233-
234-
#### implemented and partly working
235-
Wire/I2C
236-
237-
#### tested, but not working
238-
`alternateFunctions()`
239-
240-
#### not tested
241-
`ShiftIn()`
242-
`random()`
243-
`srandom()`
244-
245-
#### not implemented
246-
`yield()`
247-
`tone()`
248-
`noTone()`
249-
`pulseIn()`
250-
`pulseInLong()`
251-
module WCharacter
252-
module WString
253-
254-
255-
#### Unresolved problems
256-
257-
The compile environment needs to detect which interrupts are actively used
258-
and link only the needed ones into the binary. See test/digitalWrite:
259-
Compiling with the straight Makefile.classic does not add UART interrupt
260-
routines. But when using the sduino.mk Makefile the two UART interrupt
261-
routines are pulled into the binary by the interrupt table in main.c.
262-
263-
264-
265-
## Alternative solutions
266-
267-
The SPL (standard peripheral library) [offered by
268-
ST](http://www.st.com/en/embedded-software/stsw-stm8069.html) is very
269-
powerful and very similar to the one used for the STM32 CPU series offering
270-
a relatively easy upgrade path in case a project outgrows the capabilities
271-
of the 8-bit STM8 series. But using that library is not very intuitive and
272-
still requires a fairly detailed knowledge of the CPU internals.
273-
274-
275-
276-
277-
## Further reading and application notes
278-
279-
[project documentation files](https://github.com/tenbaht/sduino/blob/master/docs/index.md).
280-
More in detail information about supported boards, tools and the API.
281-
282-
[PM0051](http://www.st.com/resource/en/programming_manual/cd00191343.pdf):
283-
STM8AF Flash programming manual
284-
[UM0470](http://www.st.com/resource/en/user_manual/cd00173911.pdf):
285-
STM8 SWIM protocol and debug manual
286-
[AN2658](http://www.st.com/resource/en/application_note/cd00176594.pdf):
287-
Using the analog-to-digital converter of the STM8S microcontroller
288-
289-
Many examples and presentations about the STM8S:
290-
https://github.com/VincentYChen/STM8teach
291-
It contains the SPL examples from ST, the most useful resource on the STM8:
292-
https://github.com/VincentYChen/STM8teach/tree/master/code/Project/STM8S_StdPeriph_Examples
293196

294-
Using the ADC:
295-
http://blog.mark-stevens.co.uk/2012/09/single-scan-adc-on-the-stm8s/
296197

297-
Example for RS-232 handling with SPL:
298-
https://sourceforge.net/p/oggstreamer/oggs-stm8-firmware-001/ci/master/tree/rx_ringbuffer.c
299198

300-
[AN3139](http://www.st.com/resource/en/application_note/cd00262293.pdf):
301-
Migration guideline within the STM8L familiy

0 commit comments

Comments
 (0)