Skip to main content
BlueBus firmware is designed for the PIC24FJ1024GA606 microcontroller and can be built using Microchip’s development tools. The project includes both bootloader and application firmware.

​
Development environment

​
Required tools

ToolVersionPurpose
MPLAB X IDELatestIntegrated development environment
XC16 CompilerLatestC compiler for PIC24 devices
MPLAB Code Configurator (Optional)LatestPeripheral configuration

​
Installation

1

Download MPLAB X IDE

Download from the Microchip website
  • Available for Windows, macOS, and Linux
  • Install following the platform-specific instructions
2

Install XC16 compiler

Download and install the XC16 compiler from Microchip
  • Free version supports optimization
  • Install before opening the project in MPLAB X
3

Clone the repository

git clone https://github.com/tedsalmon/BlueBus.git
cd BlueBus/firmware

​
Project structure

The firmware is organized into two main projects: 
firmware/
├── bootloader/          # Bootloader project
│   ├── main.c          # Bootloader entry point
│   ├── lib/            # Bootloader libraries
│   │   ├── protocol.c  # Upgrade protocol
│   │   ├── flash.c     # Flash memory operations
│   │   ├── uart.c      # UART communication
│   │   └── eeprom.c    # EEPROM storage
│   ├── mappings.h      # Hardware pin mappings
│   ├── sysconfig.h     # System configuration
│   └── Makefile        # Build configuration
└── application/        # Main application firmware
    ├── Makefile        # Build configuration
    └── ...

​
Building the bootloader

The bootloader occupies memory addresses 0x0800 to 0x17FF and is protected from being overwritten during firmware upgrades.

​
Using MPLAB X IDE

1

Open the bootloader project

  • Launch MPLAB X IDE
  • Open firmware/bootloader/bootloader.X
  • Wait for project to load completely
2

Select build configuration

Choose the appropriate configuration from the toolbar:
  • Debug: Includes debug symbols
  • Release: Optimized for production
3

Build the project

  • Click the “Build” button or press F11
  • Output files will be in dist/{configuration}/production/

​
Using command line

cd firmware/bootloader
make clean
make all
The resulting .hex file will be in the dist/ directory.

​
Building the application

The application firmware starts at address 0x1800 with the entry point at 0x2000.

​
Using MPLAB X IDE

1

Open the application project

  • Launch MPLAB X IDE
  • Open firmware/application/application.X
2

Configure build settings

Verify compiler optimization settings:
  • Right-click project → Properties
  • Select XC16 Compiler → Optimizations
  • Recommended: Optimization level 1 or higher
3

Build the project

  • Click “Build” or press F11
  • Monitor the Output window for compilation progress

​
Using command line

cd firmware/application
make clean
make all

​
Memory configuration

​
Bootloader memory layout

The bootloader linker script (bootloader.gld) defines the memory regions: 
#define BOOTLOADER_BOOTLOADER_START  0x800
#define BOOTLOADER_APPLICATION_START 0x1800
#define BOOTLOADER_APPLICATION_VECTOR 0x2000
#define BOOTLOADER_APPLICATION_END   0xAB000
  • Bootloader code: 0x0800 - 0x17FF (6 KB)
  • Application space: 0x1800 - 0xAB000 (~676 KB)
  • Maximum addressable: 0xAA800 (698 KB total flash)

​
Interrupt vector table

The bootloader uses alternate interrupt vectors: 
// Bootloader mode
IVT_MODE = IVT_MODE_BOOT;  // INTCON2bits.AIVTEN = 0

// Application mode
IVT_MODE = IVT_MODE_APP;   // INTCON2bits.AIVTEN = 1
The application must be compiled with the alternate IVT enabled, otherwise interrupts will not function correctly after booting from the bootloader.

​
Key configuration values

​
System configuration

From mappings.h: 
#define BOOTLOADER_PLATFORM "BLUEBUS_BOOTLOADER_2_4"
#define BOOTLOADER_TIMEOUT 100  // milliseconds

​
UART settings

#define SYSTEM_UART_MODULE 2
#define UART_BAUD_115200
#define UART_PARITY_ODD  // Bootloader uses odd parity

​
EEPROM configuration addresses

#define CONFIG_SN_ADDRESS_MSB 0x00
#define CONFIG_SN_ADDRESS_LSB 0x01
#define CONFIG_FIRMWARE_VERSION_ADDRESS_MAJOR 0x02
#define CONFIG_FIRMWARE_VERSION_ADDRESS_MINOR 0x03
#define CONFIG_FIRMWARE_VERSION_ADDRESS_PATCH 0x04
#define CONFIG_BUILD_DATE_ADDRESS_WEEK 0x05
#define CONFIG_BUILD_DATE_ADDRESS_YEAR 0x06
#define CONFIG_BOOTLOADER_MODE 0x07

​
Flash memory operations

The bootloader implements low-level flash operations:

​
Flash erase

From protocol.c:ProtocolFlashErase(): 
uint32_t address = BOOTLOADER_APPLICATION_START;  // 0x1800
while (address >= BOOTLOADER_APPLICATION_START &&
       address <= BOOTLOADER_APPLICATION_END) {
    FlashErasePage(address);
    address += _FLASH_ROW * 16;  // 1024 instruction blocks
}
Pages are erased in 1024-instruction blocks (2048 bytes).

​
Flash write

From protocol.c:ProtocolFlashWrite():
  • Writes two 24-bit instruction words (6 bytes) at a time
  • Automatically skips addresses below 0x1800 (protected bootloader region)
  • Validates each write operation

​
Hardware dependencies

​
Microcontroller

  • Device: PIC24FJ1024GA606
  • Architecture: 16-bit modified Harvard
  • Flash: 1024 KB (instruction space)
  • Clock: 16 MHz (with PLL for 32 MHz instruction cycle)

​
Peripherals used

PeripheralPurpose
UART1Bluetooth module communication
UART2USB/System communication (firmware upgrades)
SPI1External EEPROM (configuration storage)
Timer1System millisecond timer

​
Compilation output

Successful builds produce several files:
FileDescription
*.hexIntel HEX format (used for programming)
*.elfELF executable (contains debug symbols)
*.mapMemory map (address allocation)
*.lstAssembly listing
Only the .hex file is needed for firmware upgrades. The other files are useful for debugging and analysis.

​
Common build issues

​
Compiler not found

Error: “Cannot find compiler executable” Solution:
  • Verify XC16 is installed
  • In MPLAB X: Tools → Options → Embedded → Add the XC16 installation path
  • Typical paths:
    • Windows: C:\Program Files\Microchip\xc16
    • macOS: /Applications/microchip/xc16
    • Linux: /opt/microchip/xc16

​
Memory overflow

Error: “region ‘program’ overflowed” Solution:
  • Reduce code size by enabling optimizations
  • Check that the linker script matches your device memory
  • Review large data structures or arrays

​
Missing dependencies

Error: “No such file or directory” for header files Solution:
  • Ensure all source files are in the project
  • Check include paths in project properties
  • Verify XC16 peripheral libraries are installed

​
Programming the device

After building, program the device using:
  • PICkit 3/4: Direct ICSP programming
  • ICD 3/4: In-circuit debugging and programming
  • USB Bootloader: For application firmware only (bootloader must already be present)
When programming the bootloader via ICSP for the first time, ensure you program both the bootloader and a valid application, or the device will remain in bootloader mode indefinitely.

Build docs developers (and LLMs) love

Get started for freeTalk to us