I had a small try on "piklab", development environment for PIC microcontrollers on Linux. I could say that it is "MPLAB experience on Linux". I summarized this article to introduce piklab, as the result was much better than I expected.

In the article, I'll explore installation of piklab, using gpasm assembler and sdcc compiler, building and download a small software, and basic debugging functions. Also making the target board to demonstrate simple LED display circuit by PIC16F819 controller as the main device.

About piklab

piklab is tool suite including GUI-based IDE for PIC/dsPIC microcontroller development on Linux. It is designed to be used like MPLAP which is provided by Microchip, and most users would be able to work on it without training much time. piklab is free and open-source software and licensed under GPL.

　The home page of piklab is ... here.

PIC development environment

ICD2

There are several types of PIC programmers available. I'm using genuine ICD2 because I thought it would have less troubles and I'd be able to get helpful information on internet.

ICD2 has an RJ-11 6-wire connector for ICSP programming. I prepared a simple adapter to connect ICSP lines to target boards.

The adapter has a toggle switch to completely disconnect ICSP signal lines (PGC/RB6, PGD/RB7) from target borads. I'm thinking about smarter circuits by using electornic switching devices although the current method has no trouble and such improvement may not be necessary so soon.

Please refer to piklab support information about other PIC programmers.

The list of supported pic mcu's are shown in "Supported device" in piklab site. Note that debugging with some devices is not supported even though programming them is supported.

MPLAB

I prepared MPLAB environment on Windows XP. I utilized its firmware directory later in this article, and it would be good if you have MPLAB ready for reference use. It seems MPLAB works on WINE environment, but not tested in the article.

I skip detail explanation about MPLAB as there are plenty of good reference on internet.

Installation

In this article Fedora 12 is used as PC Linux platform. All software programs are installed by using official Fedora repository. I believe there is no big difference in other version Fedora or Ubuntu.

• gputils

This package installs PIC assembler and related tools.
The version was 0.13.7 beta. (shown with "gpasm --version")
The homepage of gputils is here: http://gputils.sourceforge.net/.

• SDCC

This package installs C compiler that supports small microcontrollers like 8051, Z80 etc.
The version was 2.9.0. (shown with "sdcc-sdcc --version")
The homepage of SDCC is here. http://sdcc.sourceforge.net/.

• piklab

Installed piklab simply by choosing from repository.
The version was 0.15.9です. (shown with "piklab --version")

After installation is completed, you can start piklab from "Menu" > "Application" > "" > piklab. The snapshot of piklab is shown in the left.

Setting piklab

Start piklab first time and make proper settings.

Setting Toolchain

This set up for assembler and C compiler for build your projects.

• setting gpasm

Open the setting dialog from piklab menu: [Settings] -> [Configure Toolchains...], and then choose [Assembler] - [GPUtils] item.

No special setting is necessary here. Just to check if piklab has found all of "gpasm", "gplink" and "gplib" commnads.



• setting sdcc

sdcc project seems to have changed its executable program name, and you need to specify "sdcc-sdcc" instead of just "sdcc". Piklab sdcc setting dialog, however, doesn't allow change of program name itself. This time I avoided errors ("sdcc not found") by making a link to sdcc-sdcc like following.

$ su
# cd /usr/bin
# ln -s sdcc-sdcc sdcc
# exit
	

After the procedure opening again piklab dialog from its menu: [Settings] -> [Configure Toolchains...], then choose [C Compiler] - [Small Device C Compiler]. You'll see that piklab has found sdcc.

setting ICD2 programmer

• setting port (USB)

First, connect ICD2 to PC. Open dialog from piklab menu: [Settings] -> [Configure Programmers...] and choose [ICD2 Programmer]. In [Port Selectoin], choose [USB] as the port and confirm its status says "Connection: Ok".



• specify firmware directory

From MPLAB installed on Windows xp, copy firmware folder (by default, it should be C:\Program Files\Microchip\MPLAB\ICD2) and its content into some good place on Linux PC. In [ICD2 Programmer] dialog and [Specific] tab, specify the firmware folder for [Firmware directory].



• About access rights on USB/ICD2

If your Linux system doesn't permit your write access to USB ports (or serial ports), piklab cannot communicate with any programmer or debugger conntected to your PC. In that case piklab will put out an error of "Connection: Error", and you need fix your system settings.

First you can check if your ICD2 is correctly connected on USB bus.

$ lsusb
Bus 005 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 004 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 003 Device 002: ID 04d8:8001 Microchip Technology, Inc. ICD2 in-circuit debugger
Bus 003 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 002 Device 003: ID 062a:6301 Creative Labs 
Bus 002 Device 002: ID 04d9:0022 Holtek Semiconductor, Inc. 
Bus 002 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

In the example above, you can see the connected ICD2 is identified as "Device 002" on "Bus 003". It means ICD2 will be accessed through the device file of: /dev/bus/usb/003/002. Next, let's check the permission setting.

$ ls -l /dev/bus/usb/003/002
crw-rw-r--. 1 root root 189, 257 2010-04-21 13:06 /dev/bus/usb/003/002

This result tells that the device file is permitted R/W access to the group of "root", not to everybody. Now you can join the group "root" to talk through the device file. The permitted group may be different from system to system. It may be "uucp", "lp", "root" etc.
You can join any group by Linux administrative tool: from menu, [System] -> [Administration] -> [Users and Groups] (if you are using Fedora 12 English desktop).

setting ICD2 debugger

Setting ICD2 debugger is similar to ICD2 programmer.

• setting port (USB)

First, connect ICD2 to PC. Open dialog from piklab menu: [Settings] -> [Configure Programmers...] and choose [ICD2 Debugger]. In [Port Selectoin], choose [USB] as the port and confirm its status says "Connection: Ok".



• specify firmware directory

From MPLAB installed on Windows xp, copy firmware folder (by default, it should be C:\Program Files\Microchip\MPLAB\ICD2) and its content into some good place on Linux PC. In [ICD2 Debugger] dialog and [Specific] tab, specify the firmware folder for [Firmware directory].

Connect to ICD2

Select [ICD2 Programmer] from [Project Manager] in the left pane. And then from menu, connect by choosing [Programmer] -> [Connect].

At this point you'll encounter errors like "low Vcc" or "Device ID" because no target board is connected. It will disappear after a target board is ready for programming. Let's continue.

The target spec

Now we start preparing the target board and programming software. My first target circuit is built on solderless breadboard. The main MCU is pic16f819 which I had in my part box. In this article, I touch upon I/O port and timer module to control LED display.

Target circuit

This is the schematic used for piklab testing (Series resistors to LED are all 1kΩ. Other resisters are 10kΩ). Four digits of 7-seg LED's are wired to be lit dynamically by shape of characters from Port B (RB0..7) and selection of digits from Port A (RB0..4). To be simple, digit select drivers are implemented with digital transistors. The system clock is set as low as 4MHz because it reduces the number of parts and it is safe to run on breadboard. The operation is rather slow with this clock setting, but instead, it will work with lower Vcc, like two AAA batteries.

Target software

By using timer interrupt the software selets 7-sed LED digits to light them up with each characters sequentially.

• interrupt
1. restart TMR0
2. count up ticker
3. select next 7-seg LED to drive
4. output its character shape to the LED
• main
1. initiallize ports, timers, system clock and watchdog
2. initiallize ticker and LED buffers
3. set up TMR0 interrupt and enable it
4. main loop
1. convert ticker value to decimal digits
2. write decimal digits LED buffer
3. repeat main loop eternally

The feature is very limited because this article is mainly for explanation of development/debugging with piklab. To make something useful (like a clock or counter) with this circuit you may need to add key input and design man-machine interface.

Create project (gpasm)

New project

　First, create a new project using assmebler.

　From piklab menu launch project wizard by selecting [Project] -> [New Project...]. And then fill necessary information like following:

Basic Settings:
Name:	Name of your project.
Directory:	Directory where the project is created.
Device:	PIC MCU name for the project. example："PIC16F819"
Toolchain:	Toolchain for the project. Herein choose "GPUtils" to use assmebler
Programmer:	Programmer for the project. example："ICD2 Programmer"
Source Files:
Specify the source files that your project will initially have.	Choose "Create template source file." to arrange template files.

With the example above, piklab will create your project with skeleton source files (that do nothing) automatically, and you can start writing program which contains basic interrupt handler and main routine.

Writing source code

Using piklab built-in editor, change config bits around the top of the source file so that it will fit to the target configuration. And then write up inside of the interrupt handler and the main function.
This is the completed (not all features are ready) source file.

; ----------------------------------------------------------------------- ; Template source file generated by piklab #include <p16f819.inc> ; ----------------------------------------------------------------------- ; Configuration bits: adapt to your setup and needs __CONFIG _WDT_OFF & _PWRTE_ON & _INTRC_IO & _MCLR_ON & _BODEN_OFF & _LVP_OFF & _CPD_OFF & _WRT_ENABLE_OFF & _DEBUG_OFF & _CCP1_RB2 & _CP_OFF ; ----------------------------------------------------------------------- ; Variables declaration INT_VAR UDATA_SHR w_saved RES 1 ; variable used for context saving status_saved RES 1 ; variable used for context saving pclath_saved RES 1 ; variable used for context saving ticker0 RES 1 ; ticker by timer0 overflow ticker1 RES 1 digit_led_1 RES 1 digit_led_2 RES 1 digit_led_3 RES 1 digit_led_4 RES 1 digit_led_out RES 1 digit_select RES 1 digit_select_bits RES 1 dp_select_bits RES 1 var1 RES 1 ; example variable ; ----------------------------------------------------------------------- ; reset vector STARTUP CODE 0x000 nop ; needed for ICD2 debugging movlw high start ; load upper byte of 'start' label movwf PCLATH ; initialize PCLATH goto start ; go to start of main code ; interrupt vector INT_VECTOR CODE 0x004 goto interrupt ; go to start of interrupt code ; relocatable code PROG CODE interrupt movwf w_saved ; save context swapf STATUS,w movwf status_saved movf PCLATH,w ; only required if using more than first page movwf pclath_saved clrf PCLATH ; << insert interrupt code >> int_tmr0_overflow ; timer0 overflow : clear and restart TMR0 bcf INTCON,TMR0IF banksel TMR0 clrf TMR0 ; count up ticker incf ticker0,f ; select next LED (repeat 0, 1, 2, 3, 0, 1, ...) incf digit_select,f movlw 0x03 andwf digit_select,f ; get port A bit number to drive call digit_column_out movwf digit_select_bits ; blank port B, and then select port A bit to drive banksel PORTB clrf PORTB banksel PORTA movf digit_select_bits,w movwf PORTA ; output next digit to port B call digit_column_get movf digit_led_out,w banksel PORTB movwf PORTB ; << end of user interrupt code >> movf pclath_saved,w ; restore context movwf PCLATH swapf status_saved,w movwf STATUS swapf w_saved,f swapf w_saved,w retfie ; function: convert digit number to port A bit pattern digit_column_out movlw 0x00 movwf PCLATH movf digit_select,w andlw 0x03 addwf PCL,f retlw b'00000001' retlw b'00000010' retlw b'00000100' retlw b'00001000' ; function: get selected digit number variable to display digit_column_get movlw digit_led_1 addwf digit_select,w movwf FSR movf INDF,w movwf digit_led_out return start ; << insert main code >> clrf INTCON ; disable interrupt banksel OSCCON movlw 0x60 ; cpu clk = 4MHz movwf OSCCON ; setup portB0..7 as output banksel TRISB clrf TRISB ; setup portA0..3 as output banksel ADCON0 clrf ADCON0 banksel ADCON1 movlw 0x06 movwf ADCON1 banksel TRISA movlw 0xf0 movwf TRISA ; disable all LED banksel PORTA clrf PORTA ; set up variables clrf digit_select clrf digit_select_bits clrf dp_select_bits ; set test pattern "1234" movlw b'00110000' movwf digit_led_1 movlw b'01101101' movwf digit_led_2 movlw b'01111001' movwf digit_led_3 movlw b'00110011' movwf digit_led_4 ; setup TMR0 overflow interrupt clrwdt banksel OPTION_REG movlw b'10000011' ;portB no pull-up, TMR0 1/16 internal movwf OPTION_REG ; enable interrupt to start TMR0 banksel TMR0 clrf TMR0 clrf ticker0 clrf ticker1 bsf INTCON,TMR0IE bsf INTCON,GIE ; main loop (do nothing) loop goto loop END

Build the project

Now build the project with the written-up source file after saving it. From piklab menu, start building by selecting [Build] -> [Build project]. It soon will complete with downloadable binary file when "Success" message is printed.

Download and run

Connect to the programmer by selecting [Programmer] -> [Connect]. Piklab will check supply voltage and device id from the connected target board.

From piklab menu choose [Programmer] -> [Program] to download the binary. After download is completed, choose [Programmer] -> [Run] to release the taget from reset condition, then the target starts.

That's the end of the explanation how to create assmebler project. The example source file can be built but not completed because it is a torturous task for me to write longer source by using PIC assembler... Now allow me to proceed to the topic of C-compiler.

Create Project (C compiler)

New project using sdcc

First, create new project using sdcc.
From piklab menu, choose [Project] -> [New Project...] to launch project wizard. Fill in following information.

Basic Settings:
Name:	Name of your project.
Directory:	Directory where the project is created.
Device:	PIC MCU name for the project. Example: "PIC16F819"
Toolchain:	Toolchain for the project. Herein choose "Small Device C Compiler"
Programmer:	Programmer for the project. Example:"ICD2 Programmer"
Source Files:
Specify the source files that your project will initially have.	Choose "Create template source file." to arrange template files.

Almost same setting with assembler projects except toolchain. Just like assembler example, piklab generates skeleton sdcc-based source file that includes one interrupt handler and one main function. It can be built as soon as the wizard finishes preparation of the project.

Writing C source code

The following is my example of C source code for the target. The final executable binary file is rather big because I considered nothing about efficient memory usage. The great thing is that it was quite easy to write in comprehensive C language. It also supports inline assmebler code, and it is better for me than using only either of assmebler or C compiler.

/* ----------------------------------------------------------------------- */ /* Template source file generated by piklab */ #include <sdcc-lib.h> #include <pic16f819.h> /* ----------------------------------------------------------------------- */ /* Configuration bits: adapt to your setup and needs */ typedef unsigned int word; word at 0x2007 CONFIG = _WDT_OFF & _PWRTE_ON & _INTRC_IO & _MCLR_ON & _BODEN_OFF & _LVP_OFF & _CPD_OFF & _WRT_ENABLE_OFF & _DEBUG_OFF & _CCP1_RB2 & _CP_OFF; int ticker0; int digit_select; int digit_select_bits; int digit_led_1; int digit_led_2; int digit_led_3; int digit_led_4; int reg0; int reg1; void isr() interrupt 0 { /* interrupt service routine */ TMR0IF = 0; TMR0 = 0x80; ticker0++; digit_select++; if (digit_select > 3) { digit_select = 0; } switch (digit_select) { case 0: PORTA = 0x01; PORTB = digit_led_1; break; case 1: PORTA = 0x02; PORTB = digit_led_2; break; case 2: PORTA = 0x04; PORTB = digit_led_3; break; case 3: PORTA = 0x08; PORTB = digit_led_4; break; default: PORTA = 0x00; PORTB = 0x00; break; } /* << insert interrupt code >> */ } // variables for main // int var1; int var2; int i; char flag1; char flag2; char state; int hex_to_led(int in) { int out; switch (in) { case 0: out = 0b01111110; break; case 1: out = 0b00110000; break; case 2: out = 0b01101101; break; case 3: out = 0b01111001; break; case 4: out = 0b00110011; break; case 5: out = 0b01011011; break; case 6: out = 0b01011111; break; case 7: out = 0b01110010; break; case 8: out = 0b01111111; break; case 9: out = 0b01111011; break; case 10: out = 0b00000000; // blank break; case 11: out = 0b00000001; // minus break; default: out = 0b01001001; break; } return out; } void main() { /* << insert code >> */ INTCON = 0; OSCCON = 0x70; ADCON0 = 0; ADCON1 = 0x06; TRISA = 0xf0; PORTA = 0x00; TRISB = 0x00; PORTB = 0x00; ticker0 = 0; digit_select = 0; digit_select_bits = 0; digit_led_1 = 0x30; digit_led_2 = 0x6d; digit_led_3 = 0x79; digit_led_4 = 0x33; _asm clrwdt _endasm; OPTION_REG = 0x83; TMR0 = 0; TMR0IE = 1; GIE = 1; state = 0; while (1) { // led display var1 = ticker0 / 64; flag1 = 0; if (var1 < 0) { flag1 = 1; var1 = -var1; } i = 0; while (var1 >= 1000) { i++; var1 -= 1000; } if (flag1 == 0) { var2 = hex_to_led(i); digit_led_1 = var2; } else { digit_led_1 = hex_to_led(11); } i = 0; while (var1 >= 100) { i++; var1 -= 100; } var2 = hex_to_led(i); digit_led_2 = var2; i = 0; while (var1 >= 10) { i++; var1 -= 10; } var2 = hex_to_led(i); digit_led_3 = var2; var2 = hex_to_led(var1); digit_led_4 = var2; } }

Build and run

Completely same with assembler project. Just connect to the programmer and download executable binary, and run.

Usually you need to test and debug the software before it brings you expected result. As next step, I'd like to explore some debugging features of piklab.

Debug

In this section I'd like to try piklab debugger's features. Piklab project says its debugging functions are still on development, but as far as I checked, its basic functions are working well enough to investigate causes of bugs. For small hobby projects it would be sufficient in most cases.

Connect ICD2 as a debugger

Select [ICD2 Debugger] as the programmer in the left pane of [Project Manager]. Note that piklab provides debug function to limited devices even if it supports programming. See piklab homepage for details.

Turn on DEBUG_ON bit

Add "DEBUG_ON" in the configuration word around the top of the source code. After building the project, connect to ICD2 debugger.

Set a breakpoint

A test run with a breakpoint. Move to the line of souce code where you want to break, and set a breakpoint with right-click menu. After starting the target, MCU will stop if the specified line is executed.

Watch variables

You can use watching feature just select variables from left pane of "Watch". Each time MCU stopps, the watched variables are updated with its new values.

Step execution

If you choose step execution command when MCU pauses, the program executs next instruction and stopps again. It appears that piklab perform step execution on assembler instruction basis, and you may have to press several times to step forward to next line of C source code. In some cases it is better to set up a new breakpoint.

Inspect generatetd code

Piklab can show you generated assembler code from sdcc source file easily. Move to the line you like and look into its assembler code by right-click menu [Show disassembly location].

Note

Precaution

If your target configuration utilizes MCLR pin as general purpose I/O, piklab cannot hold MCU in reset condition after download, therefore MCU starts immediately. In that case you need to take care of ICSP-related pins (including MCLR) so that it won't interfere other target features if those pins are used as I/O pins.

Header file and constants for registers

Sdcc may use different identifiers for MCU register names that other C compiler defines. Those symbols are defined in the header files. If you encounter indetifier or definition errors, you may want to check header file content for the device.

Header files are in /usr/share/gputils/header (Fedora12).

Control from command line

Sometimes character based UI is quick and useful, for example, when you just want to download binary file. The following examples may be useful for such purposes.

• (sdcc) Compile single source file
sdcc-sdcc -mpic14 -p16f819 pictest.c
• (piklab) Connect to the programmer
piklab-prog -c connect -p icd2 -d 16f819 -t usb
• (piklab) Download compiled HEX file
piklab-prog -c program -p icd2 -d 16f819 -t usb pictest.hex
• (piklab) Reset and restart the target
piklab-prog -c run -p icd2 -d 16f819 -t usb

Finally...

PIC microcontrollers give us plentiful device lineups with abundant supply, low price and good reference books in Japan. With those merits a lot of hobbists are enjoying DIY projects with PIC MCU. I think PIC MCU is a good choice in many cases because of its wide variety of peripheral features to optimize cost effectiveness.

Small scale MCU like PIC is very practical and useful because you can quickly build up your projects or prototypes with less money and efforts. To maximize its merits, it is always important to shorten learning and preparation time for development. C compiler usage is very helpful when you need to quickly develop with new devices. Piklab, sdcc and gputis are all free and open source software tools working on Linux, and no reason to avoid them when you try PIC development on Linux. Thank you to everyone who works for the excellent software projects!!

---

Back to homepage