update documentation for Board Manager installation method

tenbaht · tenbaht · commit 4f1c8c32d826 · 2017-10-23T16:34:39.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,8 +5,11 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
+
+## [0.3.0 - 2017-10-23]
 ### Added
 - integration into the Arduino IDE
+- support for easy installing via the Arduino Board Manger
 - support for serialEvent()
 
 ### Changed
diff --git a/README.md b/README.md
@@ -42,6 +42,7 @@ Arduino IDE versions 1.8.5 and 1.6.13 are tested, but any version >=1.6.6
 should work.
 
 Supported Systems:
+
 * Linux 64 bit: Tested on Ubuntu 16.04
 * Linux 32 bit: Tested on Ubuntu 16.04
 * Windows: Tested on Windows 7. Sduino might work on XP (not tested), but
@@ -50,7 +51,9 @@ Supported Systems:
   install, but IDE integration should be easy now. Any volunteers?
 
 Start the Arduino-IDE. In File->Preferences, Settings tab, enter
-https://github.com/tenbaht/sduino/raw/master/package_sduino_stm8_index.json
+
+	https://github.com/tenbaht/sduino/raw/master/package_sduino_stm8_index.json
+
 as an Additional Boards Manager URL.
 
 Open Tools->Board:...->Boards Manager. Find Sduino by typing 'sd' into
diff --git a/board-manager/README.md b/board-manager/README.md
@@ -31,3 +31,15 @@ final package index file.
 
 
 
+## Package URLs
+
+If using attached files to github releases:
+
+URLs of the auto-generated repository archive files: 
+
+- https://github.com/tenbaht/sduino/archive/<tagname>.zip
+- https://github.com/tenbaht/sduino/archive/<tagname>.tar.gz
+
+URL of files attached to github releases:
+
+https://github.com/tenbaht/sduino/releases/download/<tagname>/<filename>
diff --git a/docs/hardware/flashtool.md b/docs/hardware/flashtool.md
@@ -48,16 +48,21 @@ SWD):
 
 ## Installation for Linux
 
-Required lines in /etc/udev/rules.d/99-stlink.rules:
+Save this as root in in `/etc/udev/rules.d/99-stlink.rules`:
 
 	# ST-Link/V2 programming adapter
 
-	# ST-Link V1, ST-Discovery boards
+	# ST-Link V1, if using a STM8S discovery board
+	# important: It needs a special entry in /etc/modprob/blacklist
 	ATTR{idVendor}=="0483", ATTR{idProduct}=="3744", MODE="0666", GROUP="plugdev"
 
 	# ST-Link/V2, the china adapter with the green plastic housing
 	ATTR{idVendor}=="0483", ATTR{idProduct}=="3748", MODE="0666", GROUP="plugdev"
 
+Using the STM8S-Discovery board as a flash programmer is a special case and
+requires [some additional
+blacklisting](Dstm8sdiscovery#usage-with-linux-and-stm8flash).
+
 
 
 ## Installation for Windows
diff --git a/docs/hardware/stm8sdiscovery.md b/docs/hardware/stm8sdiscovery.md
@@ -56,7 +56,7 @@ Save this as root in in `/etc/udev/rules.d/99-stlink.rules`:
 	# ST-Link/V2 programming adapter
 
 	# ST-Link V1, if using a STM8S discovery board
-	# important: It needs a special entry in /etc/modprob/blacklist
+	# important: It needs a special entry in /etc/modprobe.d
 	ATTR{idVendor}=="0483", ATTR{idProduct}=="3744", MODE="0666", GROUP="plugdev"
 
 	# ST-Link/V2, the china adapter with the green plastic housing
diff --git a/docs/install.md b/docs/install.md
@@ -1,95 +1,194 @@
-# Installing the needed tools
+# Installation
+
+Supported Systems:
+
+* Linux 64 bit: Tested on Ubuntu 16.04
+* Linux 32 bit: Tested on Ubuntu 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.
+* MacOS: Not tested, but should be very close to working. Will need a manual
+  install, but IDE integration should be easy now. Any volunteers?
+* Raspian/Raspberry Pi: Untested. Will require a manual install.
+
+
+## GUI install
+
+Starting with version 0.3.0 automatic IDE integration is supported via the
+Arduino Boards Manager. This is the recommanded way of installation now.
+Arduino IDE versions 1.8.5 and 1.6.13 are tested, but any version >=1.6.6
+should work.
+
+Start the Arduino-IDE. In File->Preferences, Settings tab, enter
+
+	https://github.com/tenbaht/sduino/raw/master/package_sduino_stm8_index.json
+
+as an Additional Boards Manager URL.
+
+Open Tools->Board:...->Boards Manager. Find Sduino by typing 'sd' into
+the search line. Click on the list entry, Click on Install.
+
+Now you should find a new entry "STM8S Boards" in the list at
+Tools->Board:... Choose *STM8S103F3 Breakout Board* from the list, open the
+standard Blink example from File->Examples->01. Basics->Blink and compile it
+by hitting 'Verify'.
+
+
+### using make on the command line
+
+All the needed tools are now installed, but they are not in your path or
+where the Makefile expects them to be. There is work needed here. #23
+
+
+
+## Manual install
+
+Only required if you want to use a current repository snapshot or if the GUI
+install fails for your system (please take the time to file a [bug
+report](https://github.com/tenbaht/sduino/issues)).
 
 All tools are available for Linux, MacOS and Windows, most of them even for
 Raspbian on a RaspberryPi.
 
-SDCC support for the STM8 is still quite fresh and not very mature. It
-improves significantly from version to version. Be sure to use
-[the latest snapshot build](http://sdcc.sourceforge.net/snap.php) from the
-[project site on sourceforge](http://sdcc.sourceforge.net/), not the older
-version that might be included in your distribution.
+- Clone or download and extract the
+  [repository](https://github.com/tenbaht/sduino) to a convenient location.
+- Download [the latest snapshot build](http://sdcc.sourceforge.net/snap.php)
+  for your system from the [SDCC project site on
+  sourceforge](http://sdcc.sourceforge.net/). Support for the STM8 improves
+  significantly from version to version. Do not use the older version of
+  SDCC that might be included in your distribution (Version 3.6 is
+  definitely too old).
 
+Later in the process you will unpack the SDCC archive. You only need support
+for the stm8. You can safely delete all the files related to the PIC CPUs in
+the `pic*` and `non-free` directories. That safes more than 90% of the used
+disk space and leaves only 20MB out of 240MB.
 
 
-## Linux
 
-Download the lastest snapshot build for SDCC from
-http://sdcc.sourceforge.net/snap.php and extract it under `/opt`.
+### Linux
 
-	mkdir /opt
-	tar xvjf ~/Downloads/sdcc-snapshot* -C /opt
+Link the hardware/sduino folder of the downloaded repository to your local
+Arduino hardware folder (usually in `~/sketchbook` or `~/Arduino`). Create
+the hardware folder, if not already present:
+
+	cd ~/Arduino
+	mkdir hardware
+	cd hardware
+	ln -s [the-extracted-repository]/sduino/hardware/sduino .
+
+Extract the [downloaded SDCC archive](http://sdcc.sourceforge.net/snap.php)
+under `/opt`:
 
-`make` is part of the standard repository for any Linux distribution.
-Example for Debian-type systems (like Ubuntu, Mint, Elementary etc.):
+	sudo mkdir /opt
+	sudo tar xvjf ~/Downloads/sdcc-snapshot* -C /opt
 
-	apt-get install make
+Create a link to SDCC from the tools directory of the sduino repository:
 
-`stm8flash` is included in the tools directory of this repository. Copy it
-to a convient place in your path, e.g. `/usr/local/bin`. To use it you might
-need to add a udev rule in order to access the USB port. Save this as root
-in in `/etc/udev/rules.d/99-stlink.rules`:
+	cd [the-extracted-repository]/sduino/hardware/sduino/tools
+	ln -s /opt/sdcc .
+
+`stm8flash` and `stm8gal` are both included as precompiled binaries in this
+tools directory. Create a link `linux` to the linux tools directory that
+matches your system and copy the binaries to a convient place in your path,
+e.g. `/usr/local/bin`:
+
+	ln -s linux64 linux
+	cp -av linux/* /usr/local/bin
+
+
+`make` and libusb-1.0 (needed by stm8flash) are part of the standard
+repository for any Linux distribution. Example for Debian-type systems (like
+Ubuntu, Mint, Elementary etc.):
+
+	sudo apt-get install make libusb-1.0-0
+
+Finally, add a udev rule in order to access the USB port for your flash
+tool. Save this as root in in `/etc/udev/rules.d/99-stlink.rules`:
 
 	# ST-Link/V2 programming adapter
 
 	# ST-Link V1, if using a STM8S discovery board
-	# important: It needs a special entry in /etc/modprob/blacklist
+	# important: It needs a special entry in /etc/modprobe.d
 	ATTR{idVendor}=="0483", ATTR{idProduct}=="3744", MODE="0666", GROUP="plugdev"
 
 	# ST-Link/V2, the china adapter with the green plastic housing
 	ATTR{idVendor}=="0483", ATTR{idProduct}=="3748", MODE="0666", GROUP="plugdev"
 
+Using the STM8S-Discovery board as a flash programmer requires a [special
+modprobe configuration
+entry](hardware/stm8sdiscovery#usage-with-linux-and-stm8flash).
+
 
 
-## MacOS
+### MacOS
 
-Quite similar. [Install Homebrew](https://brew.sh/) if you haven't done it
-yet, than:
+Quite similar to the Linux install. [Install Homebrew](https://brew.sh/) if
+you haven't done it yet, than install make and unpack the sdcc snapshot:
 
 	brew make
 	mkdir /opt
 	tar xvjf sdcc-snapshot* -C /opt
 
-Not sure about stm8flash, I didn't try it. Have a look at the
-[stm8flash repository](https://github.com/vdudouyt/stm8flash).
+Adopt the other steps from the Linux install. The arduino hardware folder is
+in your Documents folder at `/Users/<username>/Documents/Arduino/hardware`.
+
+Not sure about stm8flash, I didn't try it. Have a look at the [stm8flash
+repository](https://github.com/vdudouyt/stm8flash). It would be great if
+someone could summarize the procedure and send it to me together with a
+compiled binary for the repository.
+
+
 
+### Windows
 
+There is more work to do here, as it is lacking all the tools for the build
+system, a package system to install them and even a file system concept
+where to store them.
 
+#### SDCC 
 
-## Windows
+Unpack the downloaded SDCC archive into hardware/sduino/tools.
 
-Harder, but still possible. It is lacking all the tools, a package system to
-install them and even a file system concept where to store them. For
-convinience, I collected the bare minimum of needed tools in a
-[separate repository](https://github.com/tenbaht/sduino-windowstools).
-Download it and copy the directory tree into the sduino
-directory. Add the sduino/tools/bin directory to your path or move the files
-in there to a directory that is already in your path.
+#### MinGW
+
+The bare minimum of needed unix-like tools is collected in a [separate
+repository](https://github.com/tenbaht/sduino-windowstools). This is used
+for building the archive file for the Board Manger based install. Download
+it and copy the directory tree into the sduino directory.
+
+
+#### ST-Link, stm8flash
+
+If not already done, install the ST-Link driver from the ST website for
+hardware access.
 
 You are not bound to `stm8flash`, you can use the regular flash tool by ST
 as well.
 
 
+#### Using the Makefile-based build system
 
-### The individual pieces
+For IDE based builds you are done now. For use of the Makefile-based build
+system you need to update your `%PATH%`:
+
+- Add a link `c:\sdcc` to your SDCC installation directory and add this to
+  your `%PATH%`.
+- Add the `sduino/tools/win` directory to your path or move/copy/link the
+  files in there to a directory that is already in your path.
 
-All the tools in the convinience package are 32 bit. If you need the 64 bit
-versions you might have to collect them yourself.
 
-You need SDCC, `make` with some basic tools and maybe `stm8flash`. Get SDCC
-from the project website. `make` is a standard tool included in either
-MinGW/Msys or cygwin. Both are fine, MinGW/Msys is smaller. `stm8flash` from
-the [stm8flash repository](https://github.com/vdudouyt/stm8flash).
 
+#### The individual pieces
 
+All the tools in the convinience package are 32 bit. If you need the 64 bit
+versions you might have to collect them yourself.
 
-#### SDCC
+You need `make` with some basic tools and maybe `stm8flash`. `make` is a
+standard tool included in either MinGW/Msys or cygwin. Both are fine,
+MinGW/Msys is smaller. `stm8flash` from the [stm8flash
+repository](https://github.com/vdudouyt/stm8flash).
 
-1. Download the lastest snapshot build from http://sdcc.sourceforge.net/snap.php
-2. unzip into c:\sdcc (use a path name without whitespace)
 
-You only need support for the stm8. You can safely delete all the files
-related to the pic1x CPUs (that safes more than 90% of the used disk space
-and leaves only 20MB out of 240MB)
 
 
 #### MinGW
