add FAQ, minor spelling fixes, fix #76

docs/hardware/stm8blue.md

@@ -6,25 +6,39 @@ boards are my main development platform.
 
 ![Image of the STM8S103 board](stm8blue.jpg)
 
-They are very similar to the [ESP14 Wifi-boards](esp14.md) and
-most programs will work fine on those chinese gems as well.
-
-The STM8S103 breakout boards are build around a CPU STM8S103F3P6 with 16MHz
-internal oscillator, 8kB flash, 1kB RAM, and 640 byte EEPROM. The CPU
-includes a UART, SPI, I2C, PWM, 10 bit ADC, 3 timer, and up to 14 I/O pins -
-quite similar to an Atmel ATmega8.
+## Features
+
+The hardware features are quite similar to an ATmega8:
+
+Boardname		|stm8blue
+-----			|-------
+CPU			|STM8S103F3P6
+Clock			|16MHz, internal oscillator
+Flash			|8kB
+RAM			|1kB
+EEPROM			|640 byte
+I/O voltage		|3.3V
+GPIO			|14
+serial connections	|UART, SPI, I2C
+PWM			|4 (up to 7 via alternate mapping)
+ADC			|5 channel, 10 bit
+LED			|PB5 (Arduino D3), active low, shared with I2C, red
+programming interface	|SWIM, no serial bootloader
+USB connector		|mini, power only (data lines not connected)
 
 One (red) LED is connected to GPIO PB5 (CPU pin 11). This LED is low active.
 Please keep in mind that this is one of the I2C signals and **using the LED
 blocks the I2C bus**. The push button is for reset. The CPU runs on 3.3V, a
 linear regulator is integrated on the board. The micro USB connector is only
 for (5V) power supply, the data lines are not connected.
 
+![Schematic of the STMS103 board](stm8blue-schematic.png)
+
 All CPU pins are easily accessible on (optional) pin headers (pitch 2.54mm,
 perfect for breadboards).
 
-![Schematic of the STMS103 board](stm8blue-schematic.png)
-
+They are very similar to the [ESP14 Wifi-boards](esp14.md) and
+most programs will work fine on those chinese gems as well.
 
 ## Unlocking a write protected MCU
 
@@ -65,6 +79,13 @@ SWIM   		|2      		|5      	| 5
 GND    		|3      		|7      	| 3
 NRST   		|4      		|9      	| 1
 
+***Crap alert:*** Some lots of the stm8blue boards seem to have no working
+connection to GND on the SWIM connector!
+
+If the board does not respond to the flash tool when only powered from the
+SWIM connector, try powering it from the the USB connector or the power pin
+instead.
+
 
 
 ## Pin number mappings
@@ -76,7 +97,7 @@ Ideally, all these numbers would be the same and all programs could be
 compiled without changes.
 
 [Here](../developer/pin_mapping.md) I discuss some possible pin mapping
-schemes and check how close we could get the the ideal mapping.
+schemes and check how close we could get to the ideal mapping.
 Unfortunatly, it turns out that a perfect mapping is not possible.
 
 In the end I chose a simple geometric numbering for the square UFQFPN20
@@ -88,7 +109,7 @@ this mapping:
 
 
 sduino pin	| STM8S103 CPU port pin
-----------	| ---------------------
+---------:	| ---------------------
  0-2		| PA1-PA3 (PA1 and PA2 only weak output drivers)
  3-4		| PB5-PB4 (reverse order)
  5-9		| PC3-PC7

docs/usage/board-manager-install.md

@@ -23,7 +23,8 @@ Wait for the download to finsh and you are ready to blink:
 Easy, isn't it?
 
 In order to upload the compiled sketch to a connected board you need to
-[install your flash tool](../hardware/flashtool/#installation-for-windows).
+[install your flash tool](../hardware/flashtool/#installation-for-windows)
+first.
 
 
 

docs/usage/faq.md

@@ -0,0 +1,52 @@
+# FAQ/common problems
+
+## Compilation issues
+
+### ASlink-Warning-No definition of area SSEG
+
+This happens when there is no *.pde or *.ino file in the project directory,
+`Serial_begin()` is not used and only *.c files are compiled.
+
+This message means that main.c is not pulled in by the linker because there
+was no reference to main() anywhere. When processing *.pde/ino files
+`wrapper/sdcc.sh` (for IDE builds) or `Arduino.mk` (for Makefile builds) adds
+a reference to main:
+
+```
+/* add a dummy reference to main() to make sure to pull in main.c from the core library */
+void main(void);
+void (*dummy_variable) () = main;
+```
+
+If there is no pde/ino file the user has to make sure main.c is pulled in by
+the linker or define its own main().
+
+Possible ways to pull in main.c:
+
+- Use Serial_begin(): This references the variable runSerialEvent which in turn pulls in main.c (some overhead)
+- reference the variable runSerialEvent yourself: `begin(){runSerialEvent=0;}` (Overhead: 4 bytes flash)
+- add a reference to main() like above. (Overhead: 2 bytes RAM and 2 bytes flash)
+- define your own main() function.
+
+
+### Flashing fails on the new board
+
+It might be locked/write protected. [Check
+this](../../hardware/stm8blue/#unlocking-a-write-protected-mcu)
+
+
+## Hardware issues
+
+
+### My new stm8blue board seems dead and does not respond to the flash tool
+
+***Crap alert:*** Some more recent lots of the stm8blue boards seem to have
+no working connection to GND on the SWIM connector.
+
+Try connecting GND to the other GND board pin or power the board via USB.
+
+Most freshly shipped boards come with a pre-programmed blinky. If the LED
+blinks when the board is powered via USB but doesn't when it is only
+connected to the flash tool, your board is probably missing the GND
+connection.
+

docs/usage/why-stm8.md

@@ -76,7 +76,7 @@ $1.60-$3.00 for an ATmega8.
 
 **Upgrade path**: 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.
+ARM-Cortex CPUs. This makes it relatively easy to migrate existing software
+between the 8- and the 32-bit world. This is quite unique among the other
+CPUs.
 

mkdocs.yml

@@ -8,6 +8,7 @@ nav:
         - Introduction: 'index.md'
         - Automatic Installation: 'usage/board-manager-install.md'
         - Building with the IDE: 'usage/build-ide.md'
+        - 'usage/faq.md'
         - When to use an STM8S - and when not: 'usage/why-stm8.md'
         - Manual Installation: 'usage/manual-install.md'
         - Building with a Makefile: 'usage/build-cli.md'
@@ -29,7 +30,7 @@ nav:
         - Stepper library: api/Stepper.md
         - Servo library: api/Servo.md
     - Hardware:
-        - Flash tool: hardware/flashtool.md
+        - Flash tool: 'hardware/flashtool.md'
 #        - List of supported boards: hardware.md
         - 'Generic STM8S103F3 breakout board (stm8blue)': hardware/stm8blue.md
         - 'Generic STM8S003 support': hardware/stm8s003.md
@@ -74,5 +75,5 @@ nav:
 # best: flatly, yeti (light typeface), cosmo, united, spacelab
 # with search: mkdocs
 #theme: flatly
-theme: bootstrap
-#theme: mkdocs
+#theme: bootstrap
+theme: mkdocs