restructure stm8blue page, add more hints on PCB quality problems

tenbaht · tenbaht · commit 444fbb7cd5ea · 2020-10-15T12:48:29.000+02:00
diff --git a/docs/hardware/bad-etching.jpg b/docs/hardware/bad-etching.jpg
diff --git a/docs/hardware/stm8blue.md b/docs/hardware/stm8blue.md
@@ -32,14 +32,44 @@ 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).
 
 They are very similar to the [ESP14 Wifi-boards](esp14.md) and
 most programs will work fine on those chinese gems as well.
 
+## Connection to the flash tool
+
+I am using the ST-Link V2 compatible flash tool in the green plastic
+housing. The one in the metal housing uses a different pinout.
+
+Connection to the flashtool:
+
+Signal name	|P3 on CPU board	|Green flash tool|Metal flash tool
+------ 		|:-----:		|:-----: 	|:-----:
+3V3    		|1      		|2      	| 7
+SWIM   		|2      		|5      	| 5
+GND    		|3      		|7      	| 3
+NRST   		|4      		|9      	| 1
+
+
+
+## Crap alert
+
+Due to bad PCB production quality, some more recent lots (as of 2020) of the
+stm8blue boards seem to have either no working connection to GND on the SWIM
+connector or a short circuit from the SWIM pin to GND.
+
+![A nasty short to GND](bad-etching.jpg) The SWIM pin is shortend to GND
+
+Try connecting GND to the other GND board pin or power the board via USB.
+
+Most boards ship 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.
+
+
+
 ## Unlocking a write protected MCU
 
 My breakout boards came preprogrammed with a blink program and with active
@@ -65,28 +95,6 @@ another software package (see
 [issue#85](https://github.com/tenbaht/sduino/issues/85)).
 
 
-## Connection to the flash tool
-
-I am using the ST-Link V2 compatible flash tool in the green plastic
-housing. The one in the metal housing uses a different pinout.
-
-Connection to the flashtool:
-
-Signal name	|P3 on CPU board	|Green flash tool|Metal flash tool
------- 		|:-----:		|:-----: 	|:-----:
-3V3    		|1      		|2      	| 7
-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
 
@@ -176,3 +184,9 @@ to drive the LED by writing a zero to the output register.
 
 D5/D6 (PA1/PA2, OscIn/OscOut) are weaker than the other pins. Try avoiding
 these pins for LEDs and other higher current applications.
+
+
+## Schematic
+
+![Schematic of the STMS103 board](stm8blue-schematic.png)
+
diff --git a/docs/index.md b/docs/index.md
@@ -46,7 +46,7 @@ In order to upload the compiled sketch to a connected board you need to
 
 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 [API migration guidelines](api/migration.md) for
+not hard. Check out the [API migration guidelines](api/migration) for
 details.
 
 #### Communication
@@ -107,7 +107,7 @@ STM32. See [Limitations](usage/limitations.md) and the
 
 ### Supported Systems
 
-* Linux 64 bit: Tested on Ubuntu 18.04, 16.04
+* Linux 64 bit: Tested on Ubuntu 20.04, 18.04, 16.04
 * Linux 32 bit: Tested on Ubuntu 18.04, 16.04
 * Windows: Tested on Windows 7. Sduino might work on XP (not tested), but
   the ST-Link/V2 driver is not available anymore for XP.
diff --git a/docs/usage/faq.md b/docs/usage/faq.md
@@ -40,13 +40,6 @@ this](../../hardware/stm8blue/#unlocking-a-write-protected-mcu)
 
 ### 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.
-
+***Crap alert:*** There are [known quality
+issues](../../hardware/stm8blue/#crap-alert) with some more recent PCB
+production lots of the stm8blue boards.
