Setting Up the Toolchain

You will need a PIC programmer to write your own HEX files onto the badge. PICkit 3 and PICkit 4 have both been tested to work as programmers via the pin header on the badge.

The BASIC badge is based around a PIC32MX370F512H. Software is compiled using MPLABX, XC32 compiler, and legacy peripheral libraries from Microchip.

1. Download three packages:
   • Navigate to the Downloads" tab at the bottom of the Microchip Compilers page.
   • Download MPLAB® XC32/32++ Compiler v2.10 for your operating system
   • Download PIC32 Legacy Peripheral Libraries for your operating system
   • Navigate to the "Downloads" tab part way down the screen at the Microchip MPLAB X IDE page.
2. Install the packages:
   • Install the XC32 compiler first
   • Install the peripheral libraries next. IMPORTANT: You must specify the same directory as the XC32 compiler. This will likely not be the default option during install. For Linux installation this director was: /opt/microchip/xc32/v2.10/
   • Install MPLABX IDE
3. Open the MPLABX project from this repository
• A PIC programmer like the PICKIT3 is required to program your badge
• On the PIC programmer, pins 1-5 correspond to RES, V+, GND, B0, and B1 on the badge

(If your programmer isn't recognized in Ubuntu 18.04 see troubleshooting below)

Testing Your Toolchain Installation

To test that the tools are properly installed before Supercon, clone the badge firmware repository on Github. Open the project, plug in your PICkit, and click "Make and Program Device"

If all goes well, everything will work up to the point PICkit tries to communicate with a badge that's not there yet, at which time you'll see an error message like this:

Target device was not found (could not detect target voltage VDD).
You must connect to a target device to use PICkit 3.

Congratulations! You are ready to hit the ground running. Once you pick up your badge and connect it to your PICkit, the firmware upload should succeed.

User Examples for C Programming

The stock firmware includes an example program that has both a menu entry, and many of the commands that will commonly be needed to write your own C code.

• Selecting user program will run void user_program_init(void) first.
  • This is where you should do all of your program setup. This is a good function to call from your program when you want it to start over again.
• After the init function is called, void user_program_loop(void) will be called
  • This is where the main functionality of your program should be stored.
  • If this function returns, it will immediately be called again.
• millis() is a 32-bit upcounting millisecond timer. Non-blocking delays are a matter of setting a variable as millis()+1000 and then polling millis() until it is larger than this variable.

Advanced

• The screen defaults to scanning a 40x20 character array (screen will automatically update when array data changes). For direct control of the screen:
  • enable_display_scanning(0); //Turns off auto  screen scanning, value of 1 turns back on
  • view disp.h for screen manipulation functions to use in manual mode

• When directly controlling the screen, you will want to perform a screen refresh after badge wakes up from sleep
  • There is function pointer in hw.h that will call your screen refresh function on wake. Here is the example for setting which function will be executed (do this in the initialization function of your program):
  • start_after_wake = &you_refresh_function;

Troubleshooting

Upon updating to Ubuntu 18.04 it seems that Microchip's udev rules for PICkit programmers have been broken by the new systemd configuration. Here's how to fix:

(These instructions found at: https://www.microchip.com/forums/FindPost/1071004)

$ sudo systemctl edit systemd-udevd

An editor will open to create a so called override.conf file.
In the empty override file, copy and paste this two lines:

[Service]
IPAddressAllow=localhost

Enter Ctrl-O to save, then Ctrl-X to exit.

$ sudo reboot

---

Compiler error on fundamental C types, like 'void':

error: variable has incomplete type 'void'
error: expected ';' after top level declarator

Recently Microchip upgraded their compilers to default to C99 standards, but older C code (like the legacy libraries used by the badge) do not meet that standard. You'll need to go into Project Properties and, under compiler global options, change C standard to C90. 

---

fatal error: peripheral/adc10.h: No such file or directory

This error means the PIC32 Legacy Peripheral Libraries were not successfully installed. Please review installation instructions above, especially the part about specifying XC32 compiler directory.