README

A basic serial mode ISP programmer for Nuvoton N76E003, under Linux

This program is released under the GPL v2 or later license. See
COPYING.

Requirements
============

A Nuvoton N76E003 development board with UART pins, already programmed
with the Nuvoton LDROM that provides ISP programming. For instance,
that one:
  https://www.electrodragon.com/product/n76e003-mini-development-board/

Some of the blue breakout boards available on aliexpress also have the
ISP bootloader, but sellers do not advertise it.

A board without the ISP capability will need to be flashed with an
LDROM bootloader, which can be achieved by using NU-Link device or by
a gpio capable device running linux (see the last section for a link.)

A PC with a serial port, or some USB-to-UART adapter, such as a CP2102
or CH341A. Ideally this adapter is able to power the chip at 3.3V and
has a DTR line.

Connection
==========

Connect the board to the host UART like this:

       GND <--> GND
       RX  <--> TX
       TX  <--> RX
       DTR <--> Reset Pin (either P20 or RST), optional
       3.3V <--> 3.3V

The ISP module will start if the chip sees a specific connect packet
on its serial port 0 within a few milliseconds after powering up. If
it doesn't get the packet, it will boot normally.

For that to happen, start nvtispflash, which will begin polling the
chip through the serial device. The board must then be somehow rebooted.

The best way is to let nvtispflash automatically reboot the board by
triggering the DTR line. The following conditions must be met:

  - DTR is connected
  - The RPD bit is set to 1 in the chip config, meaning P20 is the
    reset pin and not just a regular pin.

If these conditiona are not met, there are 2 other ways to boot the
board in ISP mode.

If the RPD bit is set to 1, a reset button, if present, will be able
to reset the board.

  - Start nvtispflash
  - press the reset button

If this doesn't work, disconnect the 3.3V line and:
  - Start nvtispflash
  - reconnect the 3.3V line

That last method might be the only one that works on a new
board. After that, the RPD bit can bet set with the following command,
which makes repeat programming easier, provided DTR is connected too:

  nvtispflash -c rpd=1


Usage
=====

ISP programmer for Nuvoton N76E003
Options:
  --serial-device, -d    serial device to use. Defaults to /dev/ttyUSB0
  --config, -c           enable or disable some config options
  --aprom-file, -a       binary APROM file to flash
  --remain-isp, -r       remain in ISP mode when exiting
  --read-serial, -s      read serial output after programming

iHEX files must be converted to binary first. SDCC provides the makebin
tool for that purpose:

    makebin -p prog.ihx prog.bin

The file will be flashed at offset 0, which is the start address of
the chip.

Flashing the whole 14Kb shouldn't take more than a few seconds.

Config bits can be changed as well. For safety, only one is currently
supported. The option "--config rpd=1" will enable the RESET pin,
while setting it to 0 will disable it.


Example
=======

    $ ./nvtispflash  -a blink.bin
    Ready to connect
    Connected
    FW version: 0x27
    Device is N76E003
    Config:
      LOCK: 1
      RPD: 0
      OCDEN: 0
      OCDPWM: 1
      CBS: 0
      LDSIZE: LDROM=4K, APROM=14K
      CBORST:1
      BOIAP:1
      CBOV:3
      CBODEN:1
      WDTEN:15
    Flashing APROM with blink.bin
    sending block of 48 bytes
    sending block of 56 bytes
    sending block of 56 bytes
    sending block of 56 bytes
    sending block of 20 bytes
    Done
    Rebooting to APROM

Caveats
=======

Only the N76E003 is supported although other Nuvoton chips could be.

There is no error recovery. If an error happens, the program will bail
out.

nvtispflash will not work on big-endian machines. Some byte swapping
work would be needed.

Programming the config is partially supported. Programming the data
section is not supported at this moment, but should not be difficult
to add.

Sometimes programming will fail, with the ISP not responding, or
falling behind. As the communication protocol is not robust, it's
easier to stop and restart nvtispflash.

External resources
==================

A similar program written in python, as well as a bootloader flashing
software using a gpio capable device such as a Raspberry Pi:
  https://github.com/steve-m/N76E003-playground.git

An easy to build blink and uart test programs can be found in the
following project:
  https://github.com/erincandescent/libn76

The official BSP
  https://github.com/OpenNuvoton/N76E003-BSP

That BSP includes the source code for the LDROM bootloader in
  Sample_Code/ISP_UART0/Source.

The official BSP converted for SDCC usage, but with no Makefile:
  https://github.com/danchouzhou/N76E003-SDCC

Nuvoton's own ISP, with its windows source code:
  https://github.com/OpenNuvoton/ISPTool