Skip to main content
This guide walks you through setting up your development environment for BlueBus firmware development on the PIC24FJ1024GA606 microcontroller.

​
Prerequisites

Before you begin, ensure you have the following hardware and software:

​
Required hardware

  • PICkit 3 or PICkit 4 - For programming and debugging the PIC24FJ1024GA606
  • BlueBus hardware - Either a production unit or development board (v1.x or v2.x)
  • USB cable - For serial communication and firmware updates
  • BMW vehicle - With I-Bus for testing (E38, E39, E46, E53, E83, E85/E86, or R50/R52/R53)

​
Required software

  • MPLAB X IDE - Microchip’s integrated development environment
  • XC16 Compiler - Version 2.10 or compatible (C compiler for 16-bit devices)
  • Python 3.x - For firmware upload tools
  • Git - For version control

​
Installation steps

1

Install MPLAB X IDE

Download and install MPLAB X IDE from Microchip’s website.The BlueBus project uses NetBeans project files (nbproject/) for build configuration.
2

Install XC16 compiler

Download and install the XC16 compiler version 2.10 from Microchip’s website.
The project is configured to use XC16 v2.10. While newer versions may work, you may encounter compatibility issues with compiler flags or optimization settings.
After installation, verify the compiler is accessible:
xc16-gcc --version
3

Clone the repository

Clone the BlueBus repository to your local machine:
git clone https://github.com/tedsalmon/BlueBus.git
cd BlueBus
The repository structure includes:
  • firmware/application/ - Main application firmware
  • firmware/bootloader/ - USB bootloader firmware
  • hardware/ - PCB design files (v1 and v2)
  • utility/ - Python tools for firmware management
4

Install Python dependencies

Install the required Python packages for the firmware tools:
cd utility
pip install -r requirements.txt
This installs:
  • pyserial - Serial port communication
  • intelhex - Intel HEX file parsing
  • tk_tools - GUI components
5

Open the project in MPLAB X

Launch MPLAB X IDE and open the firmware project:
  1. Go to File → Open Project
  2. Navigate to firmware/application/
  3. Select the project and click Open
The project will load with the application configuration pre-selected.
6

Configure the build settings

Verify the build configuration:
  1. Right-click the project in the Projects pane
  2. Select Properties
  3. Under Conf: [application], verify:
    • Compiler Toolchain: XC16 (v2.10)
    • Device: PIC24FJ1024GA606
    • Hardware Tool: Your PICkit 3/4 or Simulator
For initial development without hardware, you can use the built-in simulator by selecting Simulator as the hardware tool.

​
Building the firmware

Once your environment is set up, you can build the firmware:

​
Build targets

The Makefile supports the following targets: 
make build

​
Build from MPLAB X IDE

  1. Click the Build button (hammer icon) in the toolbar
  2. Monitor the Output window for compilation progress
  3. The build artifacts are created in dist/application/production/
Successful builds generate:
  • application.production.hex - Intel HEX file for programming
  • application.production.elf - Executable and Linkable Format file
  • application.production.map - Memory map file

​
Build from command line

You can also build from the terminal: 
cd firmware/application
make build
The build system uses NetBeans-generated makefiles in nbproject/Makefile-impl.mk. Direct invocation of make relies on these auto-generated files.

​
Flashing the firmware

You can flash firmware to the BlueBus hardware using two methods: For production units with the bootloader installed, use the Python firmware tool: 
cd utility
python3 console_firmware_tool.py --flash ../firmware/application/dist/application/production/application.production.hex
The tool will:
  1. Detect the BlueBus device on the serial port
  2. Enter bootloader mode
  3. Erase the application flash region (up to 0xAA800)
  4. Write the new firmware
  5. Verify the write
  6. Reset and start the application
You can also use the GUI version: python3 gui_firmware_tool.py

​
Method 2: ICSP with PICkit

For initial programming or bootloader updates, use MPLAB X with a PICkit:
  1. Connect the PICkit to the ICSP header on the BlueBus board:
    • MCLR (Pin 1)
    • VDD (Pin 2)
    • VSS (Pin 3)
    • PGD (Pin 4)
    • PGC (Pin 5)
  2. In MPLAB X, click Make and Program Device (green arrow icon)
  3. The IDE will build, program, and verify the firmware
When using ICSP, ensure the BlueBus is powered either from the vehicle or an external 12V supply. The PICkit does not provide sufficient power for the BM83 Bluetooth module.

​
Verifying the installation

After flashing, verify the firmware is running correctly:
  1. Connect to the BlueBus serial port at 115200 baud, 8N1
  2. You should see the boot message: 
    **** BlueBus ****
  3. Type help to see available CLI commands
  4. Check the firmware version with version

​
Next steps

Now that your development environment is ready:
  • Review the code style guide for coding standards
  • Learn about testing procedures for validation
  • Explore the codebase structure:
    • lib/ - Core libraries (I-Bus, UART, I2C, Bluetooth)
    • handler/ - Event handlers for I-Bus and Bluetooth
    • ui/ - User interface implementations (BMBT, MID, CD53)
    • main.c - Application entry point and initialization

Build docs developers (and LLMs) love

Get started for freeTalk to us