After you’ve made your circuit boards they need to be programmed!  At a minimum you can program with the software that I’ve produced, or you might like to change things to suit your setup.  This article walks you through the process.

This article is one in a series describing how to make the Low Cost BMS.

Programming consists of the following steps:

  1. Download the source code from:
  2. Compile the code.
  3. Load the code into the board using a programming tool.

You’ll need this equipment and software:

Download the source code

Follow this link to see the source code available:
The source code is stored in projects.  In the screenshot you can see three projects for the BMS Master and one for the BMS Module.  The different Master projects are for different applications, download each project and view its Readme.txt file to see exactly what it is for.

Source code projects available on SourceForge

Install the software tools

To work with the projects you’ll need to install MPLABX IDE.  This is provided by Microchip, the company that makes the PIC microcontrollers used by the BMS.  MPLABX IDE is where you write your code, compile it, debug it and finally upload it to the PIC.  It is free and is available for Windows, Linux and Mac.
Install it, but it’s simplest if you don’t run this program until you install the XC8 compiler.

To program these PIC microcontrollers you’ll also need the XC8 compiler.  Download and install this after installing the MPLABX IDE.
It should automatically set itself up so that the MPLABX IDE will find it.  You don’t ever need to run the compiler separately, on installation it is integrated into the IDE.

Open the projects

Each source code project is stored as a folder.  Copy the folder to a place where you will work on it, then open the project in MPLABX IDE.  All the settings are included in the project, so hopefully the configuration will be correct.
It’s a good idea to check the XC8 version when you first open a downloaded project, since your XC8 might be a later version.  Open a project, for instance in the screenshot I have the project BMSModule.  Right click on the project name and view the project properties.

MPLABX IDE showing the Project Properties window

In the screenshot, in the Compiler Toolchain window, you can see two versions of XC8.  I’m using version 2.32, but it has previously used version 2.30.  If you are using a later version then it should list it here, and you can select it to make sure it uses that one.  Just click on it and press the OK button.


Compiling is the term used for converting the text that you write into code that can be used by the PIC microcontroller.  We’re not ready yet to program a board, but running a compile is a good test to check that everything is set up correctly so far.
Click on the button to ‘Clean and Build Project’ (the hammer and broom button).  An output window should appear with a running commentary on what it is doing.  You are looking for a summary at the end with the words “BUILD SUCCESSFUL”. There may be warnings along the way which you can ignore.

Output Window showing that the build was successful (green text towards the end)

If you receive errors indicating that the build was not successful, hopefully the text is helpful enough that you can figure out what needs to be done to fix them.  There is a large community using the MPLABX IDE, so Google is your friend!

Program a board

To program the boards you’ll need a PICkit programming tool.  You plug one end into the USB port of your computer, and the other end onto your circuit board.  I have a PICkit 3, and the version for sale as of the time of writing is the PICkit 4.  You can buy the PICkit direct from the manufacturer Microchip, but it will probably be cheaper and quicker to get them from an electronics store with a local warehouse, such as RS Components or Element 14.

The PICkit 3, plugged into a BMS Master board on the left and a USB cable on the right.

Plug the PICkit into your computer via the USB cable.  Then open MPLABX IDE and open a project.  First run a Clean and Build, as above, then press the ‘Make and Program Device’ button.  A window should pop up saying that the “last tool used for this project is unavailable”.  If all is well then you should find your PICkit in the dropdown list.  If your PICkit is not listed, the MPLABX IDE may not have found it on the USB bus.  I find that for my system it can matter which order I do things.  I find that I need to first start the computer, then plug in the tool, then run the software.  If it doesn’t work on one USB outlet, try another.
Once the tool is found you can press OK and the IDE will attempt to program your device.  But it isn’t connected to a board yet, so it will fail, probably with an error message that the device was not found.
To connect your device, run wires from the connector on the end of the PICkit to the 5 pin socket on the PCB.  Note that there are 6 pins in the socket on the PICkit, we only use the first 5.  Connect pin numbers 1-1, 2-2 etc.  I’ve made myself a cable like in the picture, make sure it is long enough to be practical.

Programming cable using two IDC sockets.  To connect to the PICkit I use a header plugged into the socket as shown.  Note that I’ve marked pin 1 with a black line.

Your board needs to be powered to program.  For the Module board, this means connecting it to a power supply of about 3-4 VDC.  This could be a cell, or an adjustable benchtop power supply is handy.  The Master board runs on 12 V, and I find that a small 12 V lead-acid battery is handy.
Once the board is powered, connect the PICkit and press the ‘Make and Program Device’ button in the IDE.  The system should program the device and report back that it was successful.
Once programmed, it is a good idea to test all the functions of your board, so that you aren’t surprised by something not working when you go to use it!  You may want to set up a test rig to do this.

Test rig for the BMS Master board (blue).  My 12 V source is a grey battery, which runs through the on/off switch.  I have an LCD screen, two buttons and 5 relays.  There are also leads that run off to BMS Module boards.  This lets me program the board, then test all input and output functions.

Introduction to the code

The source code is written in the programming language C.  Look for the text files (.txt) in the project that describe how the code works.  Not all of these are listed in the IDE, so look in the folder to see them all.

The source files (.c) contain the actual program code.  If the project you downloaded does what you need, then you shouldn’t need to modify these.  However, if you need to change the logic of how things work, the .c files are where you go. 

You will need to tinker with the header files (.h).  These contain definitions, declarations and other things that the code needs.  Look through these files for parameters that you need to change for your cells.  For instance, in main.h:

  • VERSION1 & VERSION2 are the two lines displayed on the LCD of the Master that display the version number.
  • PARALLEL is how many CellTop Modules you will use in parallel (will often be zero).
  • HiCellVolts is the upper voltage limit for your cells.
  • VOLTRANGE is a number that sets the upper and lower voltage limits able to be transmitted from the Module boards.  Make sure this is the same for the Master and Module code.
  • There are many more!

To understand the code, I’d recommend that you program a Master board (complete with buttons) and two Module boards.  Connect the communications lines up and experiment with the voltages on the module boards.  Then change parameters in the code and make sure you understand what is happening.

A simple modification

There are lots of parameters in the source code that you can change even if you don’t understand the exact workings of every arcane term.  Most of these parameters are in the BMS Master project.
For instance, open up the Header Files menu in the window on the left.  Open the main.h file, and it will appear on the right.  In this file you’ll see lots of #define lines.  Find the two lines that define VERSION1 and VERSION2.  This is the message displayed on the LCD, so try changing the text within the quote marks to something all your own.  It is a two line LCD with 16 characters on each line, so keep each line to 16 characters or fewer.

Editing the code in the BMSMaster_E63 project.

Save the file, use the ‘Clean and Build’ button to compile it, then ‘Make and Program Device’ as described above.  Assuming that you have an LCD screen attached, it should display your new text.

Have fun!  And if you make your own version of the code, please consider uploading your version to the SourceForge repository.

The complete set of articles include:
The Low Cost BMS
How to Create Circuit Boards for the Low Cost BMS
How to Assemble the Circuit Boards for the Low Cost BMS
How to Program the Circuit Boards for the Low Cost BMS (this article)

Leave a Reply

Your email address will not be published. Required fields are marked *