gputils (GNU PIC Utilities) is a collection of open-source software tools for Microchip PIC microcontrollers. It serves as an open-source alternative to Microchip’s proprietary MPLAB tools, allowing developers to assemble, link, and manage PIC assembly code on Linux, macOS, and Windows.
Here is a comprehensive guide to getting started with this lightweight, powerful development suite. What is gputils?
The gputils suite provides the essential tools required to turn PIC assembly source code into executable machine code (HEX files) that can be burned onto a microcontroller. It mimics the behavior of Microchip’s legacy absolute assembler (MPASM) and linker (MPLINK), making it highly compatible with older codebases and tutorials. The core utilities included in the package are:
gpasm: The GNU PIC assembler. It converts .asm source files into object files (.o) or absolute hex files (.hex).
gplink: The GNU PIC linker. It combines multiple object files and library files into a single executable HEX file using linker scripts (.lkr).
gplib: The GNU PIC archiver. It creates and manages libraries of object files (.lib).
gpdasm: The GNU PIC disassembler. It converts HEX files back into readable assembly code for debugging or reverse engineering. Key Advantages of gputils
Cross-Platform Compatibility: Unlike older Microchip tools that locked developers into Windows, gputils runs natively on almost any operating system.
Lightweight Footprint: The entire suite occupies only a few megabytes of disk space and requires minimal system resources.
Command-Line Efficiency: It integrates seamlessly into automated build systems, custom Makefiles, and continuous integration (CI) pipelines.
Open Source: Released under the GNU General Public License (GPL), ensuring it remains free to use, modify, and distribute. Installation Guide On Linux (Ubuntu/Debian)
gputils is available in most standard Linux repositories. Open a terminal and run: sudo apt-get update sudo apt-get install gputils Use code with caution.
The easiest way to install gputils on macOS is via Homebrew: brew install gputils Use code with caution. On Windows
Windows users can download the pre-compiled installer executables from the official gputils SourceForge repository. After installation, ensure you add the installation path (e.g., C:\Program Files\gputils\bin) to your system’s PATH environment variable so you can access the tools from the command prompt. Workflow: Writing, Assembling, and Linking
To demonstrate how gputils works, let’s look at a basic workflow for a classic PIC microcontroller, such as the PIC16F84A or PIC16F877A. 1. Writing the Assembly Code (main.asm) Create a simple file named main.asm using any text editor:
TITLE “Simple gputils Example” LIST P=16F877A INCLUDE “p16f877a.inc” ; Configuration bits __CONFIG _HS_OSC & _WDT_OFF & _LVP_OFF ORG 0x0000 ; Reset vector GOTO Start ORG 0x0005 Start: BSF STATUS, RP0 ; Bank 1 CLRF TRISB ; Set Port B as output BCF STATUS, RP0 ; Bank 0 Loop: MOVLW 0xFF MOVWF PORTB ; Turn on all LEDs on Port B GOTO Loop END Use code with caution. 2. Assembling in Absolute Mode
If your project consists of just one file, you can bypass the linker and generate a HEX file directly using gpasm: gpasm main.asm Use code with caution.
This command generates main.hex (the file to flash onto the chip), main.lst (a detailed listing file), and main.cod (debug information). 3. Assembling and Linking in Relocatable Mode
For larger projects, it is better practice to write relocatable code across multiple files and link them. First, assemble the file into an object file: gpasm -c main.asm Use code with caution.
This outputs main.o. Next, link the object file using the appropriate linker script provided by gputils: gplink -m -s /usr/share/gputils/lkr/16f877a_g.lkr main.o Use code with caution.
(Note: The path to the .lkr files will vary depending on your operating system and installation directory). Ecosystem and Next Steps
While gputils handles the compilation side, a complete open-source PIC development toolchain requires a few extra components:
The Compiler (Optional): If you prefer writing in C instead of Assembly, gputils serves as the backend engine for SDCC (Small Device C Compiler). SDCC compiles C code into assembly, which gputils then assembles into HEX files.
The Programmer: To transfer the generated HEX file from your computer to the physical PIC hardware, you can use open-source programming tools like OpenOCD or pk2cmd / pk3cmd (command-line utilities for the PICkit programmers).
The IDE: You can use any modern text editor like VS Code, Sublime Text, or Vim. Most of these editors have downloadable extensions that add syntax highlighting for PIC assembly.
By mastering gputils, you free your microcontroller development from vendor lock-in, paving the way for lightweight, scriptable, and highly efficient embedded workflows. To help you get your toolchain up and running, let me know: Which operating system are you using? What specific PIC microcontroller model are you targeting? Do you plan to write code in Assembly or C?
I can provide the exact installation paths, specific configuration templates, or a customized Makefile for your setup.
Leave a Reply