BOOTLOADER

The Circle project has an integrated serial bootloader, which can be used to
speed-up the development process and to make it more comfortable. The bootloader
has been adapted from the well-known bootloader by David Welch.

To use the bootloader, you have to do the following:

1. You need a serial USB adapter (3.3V level) connected to GPIO14/15 (Broadcom
numbering) of your Raspberry Pi computer on one side and to your development
machine on the other. On the Raspberry Pi 5 the dedicated UART connector is used
to connect the serial adapter. See this document for the pinout:

https://datasheets.raspberrypi.com/debug/debug-connector-specification.pdf

2. On your development machine there must be a python3 interpreter (including the
python3-pyserial module) installed. You may also need the terminal program
"putty".

3. Add the following lines to the file Config.mk in the Circle root directory:

	SERIALPORT = /dev/ttyUSB0	(device of your serial USB adapter)
	FLASHBAUD = 115200		(baud rate for loading the application)
	USERBAUD = 115200		(baud rate used by the application)

By increasing FLASHBAUD you can speed-up to loading process very much. It
depends on your serial adapter, which baud rates are possible. Common values are
460800, 921600 or higher.

USERBAUD is the baud rate, used by the application itself, if it communicates
using the serial interface.

4. The Circle project libraries used in your application have to be build
manually using "./makeall" as described in the main README.md file.

5. You have to prepare a SD card with a FAT partition, which starts your
Raspberry Pi in bootloader mode. Go to the boot/ subdirectory and enter:

	make all

5b. If building for AArch64, then additionally enter:

	make bootloader64

After completion copy the files from boot/ to the SD card's FAT partition and in 
the destination, rename config32.txt or config64.txt (for AArch64) to config.txt.
Please note, that you have to repeat this step, if you change the parameter
FLASHBAUD in Config.mk. The built bootloader is specific for this baud rate. Put
the SD card into your Raspberry Pi, which is connected to your development
machine and power it on.

6. The bootloader starts when you go to the subdirectory of your application (or
sample program) in a shell and enter:

	make flash

7. If your application uses the serial interface itself, you can start the
terminal program "putty" directly from the shell. You have to enter "make
monitor" like you have done for "flash" before and putty should open with the
right communication parameters.

8. To start another development cycle, power off and on the Raspberry Pi, and
after rebuilding do again "make flash".


Using the Flash Tool "Flashy" (v1)
----------------------------------

The above procedure describes flashing the device using the traditional python3 based flash
tool and bootloader.  There is also a new flash tool and bootloader that provide improved 
features:

* The new flash tool waits for ack messages from the bootloader to ensure it's ready. If 
  the device isn't ready it will wait until you reset it.

* Improved reliability as the new bootloader now performs checksums and reports any errors 
  with the transfer.

* A new "fast transfer mode" effectively doubles the transfer rate by sending binary instead
  of hex encoded data.  RPi 2 can handle 2M Baud in fast mode (equivalent to 4M Baud with 
  the old flasher) and RPi 3 can handler 3M baud (equivalent to 6M).

* The new flasher tool can send magic reboot strings and wait for the device to become ready 
  before starting the transfer - which can be faster than pessimistic delays and hoping the
  device is ready.

* After flashing the new flasher tool can automatically switch into monitor mode (switching 
  baud rates if necessary) to view the output of the flashed program.

* Ability to reset the bootloader to recover from a previously cancelled or failed transfer.

* Ability to introduce a "go delay" - a delay that the bootloader will stall for between 
  receiving the go command and launching the user program.  This can be used if you need
  to see the very start of the debug log and your monitor program takes too long to start.


The new flasher tool is written in JavaScript and requires NodeJS to be installed.  To use it:

1. Make sure you have NodeJS installed

2. Go to the `tools/flashy` sub-folder and run `npm install` to install the required 
   serial port module.

3. If you're currently using an old version of the bootloader, rebuild the latest version and
   copy it to the SD card. (This is optional as the new flash script works with the old 
   bootloader but most new features won't work)

4. In your Config.mk set the variable `USEFLASHY`, along with the other serial port settings:

        USEFLASHY = 1
        REBOOTMAGIC = <magicstring>
        FLASHYFLAGS = <other command line args for the flashy script>
        SERIALPORT = /dev/ttyUSB0
        FLASHBAUD = 115200
        USERBAUD = 115200

5. Flash the device as per before:

        make flash

6. If the device is ready the transfer will start immediately, otherwise a "waiting for device"
   message will be displayed until you power cycle or reset the device.

You can also manually launch the flasher tool like so...

    node tools/flashy/flashy.js /dev/ttyUSB0 kernel7.hex --flashBaud:2000000

Or, pass additional args via the make script:

    make flash FLASHYFLAGS=--godelay:500

For a full set of command line args, run the script with --help

    node tools/flashy/flashy.js --help

For details on using this under WSL, see the [Windows build instructions](windows-build.txt)

If you want to use Flashy with the Bluetooth modules HC-05 or HC-06, please see
[these instructions](https://github.com/rsta2/circle/pull/312).


Using the Flash Tool "cFlashy"
-----------------------------

Because of recent issues with npm packages, used by the original Flashy (v1), there is
a similar tool as a native executable for Linux, Windows and macOS available now in the
Circle project, which is called "cFlashy", and which supports the most important features of
Flashy v1 in a compatible way.  To use it:

In your Config.mk set the variable `USEFLASHY`, along with the other settings for Flashy v1:

        USEFLASHY = 0

You can also manually launch cFlashy using:

        tools/cflashy /dev/ttyUSB0 kernel7.hex --flashBaud:2000000

For a full set of command line args, run cFlashy without args:

        tools/cflashy

If you want to use cFlashy with the Bluetooth modules HC-05 or HC-06, you have to set
a smaller packet size in Config.mk, like this (not tested yet):

        FLASHYFLAGS = --packetsize:32


Using "Flashy" v2
-----------------

There is a new improved version of Flashy, which is maintained in a separate
project:

	https://github.com/toptensoftware/flashy

Details about the features of this version and its installation can be found in
the project README. The configuration in Circle to use this version is very
similar as described above, with one difference. In your Config.mk you have to
specify:

	USEFLASHY = 2
