GCBASIC USB bootloader for the PIC18F - replaces the Microchip with many more functions

[Anobium]

GCBASIC USB bootloader for the PIC18F/PIC16F

I have written a replacement, written 100% in GCBASIC for an 18F/16F, USB interface and SD-card bootloader.

Aims

• Same memory layout and behaviour, so every existing card hex runs unchanged:
• the bootloader in 0x0000-0x9FFF;
• programs from 0xA000, with their interrupt vectors at 0xA008 and 0xA018;
• programs up to 0xFBFF; the last page (0xFC00-0xFFFF, with the configuration words) is never written;

• MENU during a countdown opens the card's file list.

• Improvements over the original:

• check every hex record's checksum (the original reads it but does not check it);
• check the whole file before erasing, so a bad file does not leave an empty program area (the original erases first);

• do not start an empty program area (the original's "application is valid" test is always true).

• Built from the GCBASICDemo libraries: sd_card.h, sd_fat.h, kit_base.h, the touch pads from MENU_GCB.

Programming it

The new bootloader is written to 0x0000 by an ICSP programmer. The running bootloader cannot replace itself: it only writes 0xA000-0xFBFF. Two ways:

• A board's own programmer/debugger ("Debug/Power"). Like an on-board PIC18F67J50 drives the PIC18F46J50's MCLR, PGC and PGD (user's guide DS51852A, sections 3.1, 3.4, 4.2). It works with MDB from GC Studio: C:\GCstudio\PICkitXtra\core20\lib\mdb.jar, tool skdepic18fj, programmer mode only (hwtool skdepic18fj -p). Then use program <hex>, and upload + x for a read-back. Read the configuration words with x /c8xb 0xFFF8.
• A PICkit 2 / 3 / SNAP needs J6, the "PICkit 2".

Size compared with Microchip's bootloader

All bootloaders need to reserve 0x0000-0x9FFF (40 KB):

Bootloader	Used	Free in the 40 KB
Microchip v1.3	0x0000-0x9792 (37.9 KB)	2.1 KB
Microchip v1.4	0x0000-0x8EBF (36.5 KB)	3.5 KB
GCBASIC v2.03 (before USB drive mode)	0x0000-0x48D1 (18.6 KB)	21.4 KB
GCBASIC v2.06 (USB drive mode, automatic load)	0x0000-0x76E5 (29.7 KB)	10.3 KB

Why the boundary is 0xA000. It can never move: every card .HEX is built for 0xA000. Microchip's code was close to 38 KB, and 0xA000 is the next round boundary on the 1 KB erase blocks above it, with a little room for later fixes. v1.4 then came out smaller than v1.3. This is inferred; Microchip does not document the choice.

Why Microchip's bootloader is about 36 KB, from its source and build settings:

Part	Why it is large
MDD File System (FSIO.c, 420 KB of source)	General-purpose library, configured (FSconfig.h) with FAT32, folders, file search and ALLOW_PGMFUNCTIONS, which compiles a second copy of functions for ROM strings (FindFirstpgm, FSchdirpgm). Writing and formatting are off, but the read side is still general.
SD-SPI driver (SD-SPI.c, 115 KB of source)	Covers many card types, time-outs and options.
C18 code generation	16-bit int by default (the list counters are int); 3-byte pointers that can point to ROM or RAM; a software stack for local variables; library calls such as strcpy. Optimisations were on (enable-all-optimizations in the project), so this is normal C18 output.
Bootloader framework (boot_load_hex.c, boot_media_msd.c, boot_io.c)	Layered so it could move to other media and chips.
OLED driver	Full 96-character font plus image and string functions.
Text	About 40 screen lines of 21 characters.
mTouch, soft start	Small.

Why the GCBASIC bootloader is about half that size. It is written for this one board and job:

• sd_fat.h and sd_card.h are compact and specific;
• byte and word arithmetic, with no pointer machinery;
• uncalled routines are left out by the compiler;
• no driver layers.

It does more checking than v1.4 (record checksums, a verify pass, the entry written last) in about half the space.

Using the free space. Nothing has to change. The 21 KB leaves room for features such as long-name display, a USB mode for loading programs from the PC, or a checksum shown on the start screen. The boundary itself must stay at 0xA000, so a smaller bootloader does not give programs more room.

Files

File	Purpose
GCBASIC_Bootloader.adoc	The write-up (AsciiDoc): new features compared with Microchip v1.4, use, install / remove, how it works, building, tests, limits.
BOOT_GCB.gcb	The bootloader. Holds the design, the v1.4 reference, the differences from v1.3 to v1.4 with the action taken for each, and the configuration words.
boot_flash.h	Flash erase / write / read for the PIC18F J family.
usb_msd_polled.h	USB drive mode: GCBASICDemo\usb_msd.h with endpoint 0 polled (USBPoll) instead of the USB interrupt, no #startup, plus USBStop. Made by make_usb_msd_polled.ps1; do not edit.
make_usb_msd_polled.ps1	Makes usb_msd_polled.h from usb_msd.h (run again after a change to it).
boot_newest.h	The newest .HEX on the card (root and two folder levels), from the PC's time stamps (sd_fat.h with FAT_LIST_STAMP); counts the files newer than a given stamp.
USBP_GCB.gcb	Step 1 test of USB drive mode: polled USB drive with no interrupts, then the newest-file scan; an ordinary card program.
boot_hex.h	Intel HEX parser: checks every record (digits, length, checksum, type), passes program-area bytes to HexStore, reports HexError / HexLine and counts.
HEXC_GCB.gcb	Test of boot_hex.h: checks every .HEX in \HEXTEST (or the root) and lists OK + sum, or the error and line; writes no flash.
make_hextest.ps1	Writes HEXTEST\ (good files and one-fault files) and EXPECTED.TXT, from a separate PC model of the same rules; -Card D: copies the folder to the card.
FLSH_GCB.gcb	Test of boot_flash.h, run as an ordinary program from the current bootloader.
PROGRAM_BOOT.cmd / program_boot.ps1	Programs BOOT_GCB.HEX (or a given bootloader hex) at 0x0000 through J2 and checks it byte for byte. It refuses a file without code at 0x0000, without the configuration words, with data at 0xA000, or without the 0xA008 / 0xA018 jumps; asks for YES; writes a log to Logs\. Core20 MDB in programmer mode only.
RESTORE_V14.cmd / restore_v14.ps1	Puts Microchip's v1.4 back through J2 and checks it byte for byte (asks for YES; RESTORE_V14 verify only reads and compares). Core20 MDB in programmer mode only; writes a log to Logs\.
SPEC_bootloaderhost.md	Specification of the compiler option that forwards the interrupt vectors from a GCBASIC bootloader.
build.ps1	Builds a program as GC Studio's Make HEX, writes the card file <NAME>.HEX (with :020000040000FA) and checks the code range.
Logs\	The logs of every PROGRAM_BOOT / RESTORE_V14 run (the installation history in the .adoc).
Original\	Microchip's bootloader: v1.4 hex (the restore image, verified on the board) and source (MLA); v1.3 hex images (zip) for comparison.

Usage

I have 28 programs that I have written for this bootloader. I will publish each one to a new thread over the coming weeks and months.

[Anobium]

The programs I have cover the common device classes, plus a UPS.

Scope covered

Class	Programs
CDC-ACM (virtual COM port)	MENU, CDCB, CLCK, SERL
HID boot mouse	MOUS
HID joystick	JOYS
HID boot keyboard (with the PC's lock lights)	KEYB, LOGN
HID vendor-defined (64-byte reports)	HIDC, LEVL
HID Power Device (UPS)	UPSB
Mass storage (SD card as a drive)	SDPT, SDRW, DLOG, the bootloader's drive mode

[Anobium]

UPDATED 13th Oct 2026:

The programs I have cover the common device classes, plus a UPS.

Scope covered

Class	Programs	PC side
CDC-ACM (virtual COM port)	MENU, CDCB, CLCK, SERL, CDCT	Any serial terminal (PuTTY, TeraTerm); CdcTerminal for CDCT
HID boot mouse	MOUS	None: Windows' own driver
HID joystick	JOYS	None: Windows' game controller settings (joy.cpl)
HID boot keyboard (with the PC's lock lights)	KEYB, LOGN	None: Windows' own driver
HID vendor-defined (64-byte reports)	HIDC, LEVL	HID PnP Demo (HIDC); the Level application (LEVL)
HID Power Device (UPS)	UPSB	Windows' battery driver; UPSMonitor
Mass storage (SD card as a drive)	SDPT, SDRW, DLOG, the bootloader's drive mode	Explorer; DLOG_tail.ps1 (DLOG); GCBHexLoader (bootloader)

Where the device class is standard, Windows needs no driver and no extra program, and the table says "None". The named programs are the ones in this project, or the kit's own HID PnP Demo.exe (in \Tools on the card).

Program names

There are 29 programs. Each has a four-letter name, followed by _GCB in the file names, because the bootloader shows only 8.3 file names. The USB column gives the device class; "-" means the program does not use USB.

	Name	Stands for	USB	What it does
1	DEMO	Demo	-	First demo: text on the OLED, the pot as a number and a bar, a loop counter
2	ACCL	Accelerometer	-	DEMO plus the BMA150 accelerometer: X and Y as values
3	TILT	Tilt	-	Tilt display: left/right and forward/back scales, LEVEL when flat
4	MENU	Menu	CDC	Touch-pad menu: tilt, temperature, ADC readings, and a USB COM
5	VOLT	Voltmeter	-	Analogue voltmeter: a needle dial for the pot, 0-3.3 V
6	CLCK	Clock	CDC	Real-time clock with analogue face and alarm, set and read ov
7	SCOP	Scope	-	Oscilloscope: the pot, the accelerometer and demo waveforms, with gain, trigger and hold
8	SORT	Sort	-	Sort visualiser: 64 bars sorted by five algorithms, with compari
9	ELIT	Elite	-	The 8 x 256 star systems of Elite (1984): system data, galaxy map, short-range chart
10	MOUS	Mouse	HID	USB mouse: tilt the board to move the cursor, the touch pads
11	JOYS	Joystick	HID	USB joystick: tilt is the stick, the pot is the throttle, the pads are buttons
12	CDCB	CDC Basic	CDC	The accelerometer's registers sent to a COM port, as Mic
13	HIDC	HID Custom	HID	Raw pads, accelerometer and pot for Microchip's HID PnP Demo, as the kit's HID Custom Demo
14	UPSB	UPS Battery	HID	The board as a USB UPS: the pot sets the charge, MENU
15	KEYB	Keyboard	HID	Presentation remote: the pads send the slide-show keys
16	LOGN	Login	HID	Login key: MENU types a stored login string and Enter
17	SERL	Serial	CDC	USB-to-serial adapter: a COM port on the PC joined to the chip's UART on the J4 header (3.3 V)
18	CDCT	CDC Terminal	CDC	Command terminal: single-character commands toggle LEad the pot and the temperature; works with the CdcTerminal application
19	LEVL	Level	HID	Bubble level, with a HID link to the PC Level application
20	SDPT	SD Pass-Through	MSC	The SD card as a read-only USB drive
21	SDRW	SD Read / Write	MSC	The SD card as a USB drive the PC can also write
23	FATT	FAT Test	-	Test of the FAT library: folders, files, reading, listing, deleting (102 checks)
25	LABY	Labyrinth	-	Tilt the board to roll a ball to the goal through six levels
27	WBAR	White Barrows	-	The White Barrows adventure game in 3D
29	INVD	Invaders	-	The arcade game: a marching formation, shields and three lives

"CDC" is the USB Communications Device Class, the standard that makes a USB device appear as a COM port. "HID" is the Human Interface Device class, used by keyboards, mice, joysticks and UPSes. "MSC" is the Mass Storage Class, used by USB drives.

The numbering follows this gallery's order: kit demos and tools, then USB devices, then SD card, then games.

[Anobium]

Using the GCBASIC bootloader

The bootloader starts every time microcontroller powers up or restarts. The intent is to load
your program (a .HEX file) into the microcontroller and start it.

There are three ways to load a program:

1. Menu select - choose a .HEX file that is already on the SD card.
2. USB drive - copy .HEX files to the SD card from the PC.
3. USB HexLoader - one command on the PC copies, loads and starts your program.

In every case the bootloader checks the whole file before it changes anything. A bad hex file
never replaces a good program.

Only the Menu select is available on the original Microchip bootloader.

The start screen

When the board starts you see "GCBASIC Bootloader", the logo, and a countdown from 9 to 0.

• Do nothing: your program starts.
• Press MENU: the file list opens.
• Hold MENU for 2 seconds: USB drive mode.

To get back to the start screen from a running demo, hold MENU for 2 seconds and release.

1. Menu select

Use this when your program is already on the SD card.

1. Press MENU during the countdown. The file list opens.
2. Use Up and Down to move, R to open a folder or choose a file, L to go back.
3. "Load this file?" - press R.
4. The board shows Checking, Erasing, Writing and Verifying.
5. "Loaded" - press R to start the program.

If the file has a fault, the board shows the fault and its line number, and says
"Old program kept". Nothing in the chip has changed.

Your program now starts by itself after every countdown.

2. USB drive

Use this to put new .HEX files on the SD card without taking the card out.

1. Connect the board to the PC with USB.
2. Hold MENU for 2 seconds during the countdown.
3. The board shows "PC USB drive". The PC shows a new drive called "GCBASIC SD Card".
4. Copy your .HEX files to the drive, or, carry out other file operations.
5. Eject the drive in Windows.
6. The board shows "New file:" with the name of the file you copied.
7. Press R to load and start it, or L to see it in the file list.

Always eject the drive before you unplug the cable.

3. USB HexLoader

Use this while you are writing a program in a IDE lilke GCCODE.

One command does everything.

1. Compile your program in GCCODE (F5).
2. Restart the board and hold MENU for 2 seconds (USB drive mode).

3. On the PC run via Preferences Editor

   GCBHexLoader.exe MYPROG.HEX /folder:GCBASIC /wait:60

4. The tool copies the file to the card, ejects the drive, and the board shows
   "Automatic load". A few seconds later your program is running.

You can run the command first and then put the board into USB drive mode: the tool waits
up to 60 seconds for the drive.

GCBHexLoader.exe is in C:\GCstudio\XpressLoader, and in \Tools on the SD card.

Good to know

• File names are 8.3, for example MYPROG.HEX.
• Programs must be compiled with #option bootloader 0xA000.
• Loading a program can never damage the bootloader.

[HackInBlack]

what is the target hardware for these demo's?
do you have a schematic?

[Anobium]

I will post the schematic over the next few days but all pretty simple. I will validate using my old Great Cow BASIC Pcbs and any Microchip board I have.

[Anobium]

My first program using the bootloader.

The mandatory start-up, with GCBASIC SH1106A GLCD. This is a complete first program. It compiles as it-is of the board I am using, and it provides APP_VDD soft start, gcb_logo.h the logo, and the screen is drawn with GCBASIC's GLCD commands: glcd.h with GLCD_TYPE_SH1101A (glcd_SH1101A.h) on an 8bit GLCD bus, with the 1024-byte screen buffer.

InitGLCD is called after AppPowerOn, because #StartupMethodsDisabled stops the library's own start-up. Saved under an 8.3 name, for example FRST_GCB.gcb, so that the hex has a name the bootloader listed.

#chip 18F46J50, 48
#option explicit
#option bootloader 0xA000           ' the bootloader jumps to 0xA000 (interrupts to 0xA008)
#option StartupMethodsDisabled      ' no InitSys: as using InitSys would switch APP_VDD on without a soft start and damage the USB port.
#config OSC = HSPLL, PLLDIV = 3, CPUDIV = OSC1, WDTEN = OFF, XINST = OFF, STVREN = ON, IOL1WAY = OFF

#include "kit_base.h"                ' pins, AppPowerOn (and the OLED routines the logo uses)
#include "gcb_logo.h"                ' ShowLogo: the GCBASIC logo
#include "menu_restart.h"            ' hold MENU 2 s: restart (the same in every program)

' ----- GCBASIC GLCD: the SH1101A OLED on the kit's 8080 parallel bus, with the 1024-byte screen buffer
#include <glcd.h>
#define GLCD_TYPE GLCD_TYPE_SH1101A
#define GLCD_DATA_PORT PORTD          ' D0..D7
#define GLCD_WR        PORTE.1        ' write strobe
#define GLCD_RD        PORTE.0        ' read strobe (held high)
#define GLCD_CS        PORTE.2        ' chip select
#define GLCD_DC        PORTB.5        ' data / command

#define BUILD_TEXT   "FRST_GCB build 4"

' ----- This is what InitSys would have done, minus the PORTC clear
INTCON = 0                          ' interrupts off
TBLPTRU = 0                         ' for ReadTable
APP_POWER = 1 : Dir PORTC.0 Out     ' keep APP_VDD off until AppPowerOn
OSCTUNE.PLLEN = 1                   ' the PLL is already running (48 MHz)
Wait 2 ms
SD_CS = 1 : Dir PORTC.6 Out         ' SD card and accelerometer deselected
ACCEL_CS = 1 : Dir PORTC.7 Out
Dir PORTB.0 In                      ' MENU button
WDTCON.4 = 1                        ' ADSHR: the ANCONx registers share addresses
ANCON0 = 0xE0                       ' AN0..AN3 touch pads, AN4 pot; the rest digital
ANCON1 = 0x9F
WDTCON.4 = 0
LATD = 0 : LATE = 0

AppPowerOn                          ' APP_VDD on with the soft start
InitGLCD                            ' the GLCD library (StartupMethodsDisabled stops its #startup)
ShowLogo(BUILD_TEXT)                ' the GCBASIC logo for 4 s
GLCDCLS                             ' clears the screen buffer and the display after the logo

' RAM is not cleared at start-up: set every variable before it is used

' A box on the outermost pixels (x 0 and 127, y 0 and 63), then three lines of text inside it,
' each centred. GLCDPrint at (x, y) draws the characters from x + 1, y + 1.
Box(0, 0, 127, 63)
GLCDPrint(15, 7, BUILD_TEXT)        ' 16 characters = 96 pixels: x = (128 - 96) / 2
GLCDPrint(9, 23, "Hello from GCBASIC")   ' 18 characters = 108 pixels
GLCDPrint(9, 47, "Hold MENU: restart")   ' 18 characters = 108 pixels
Do
    ' ... the program ...
    MenuPoll                        ' hold MENU 2 s: restart; use If MenuCheck = 1 Then ... for a short press
Loop

---

--------------

Enjoy this insight.