PICPIO logoPICPIO
PICPIO

How to use PICPIO

From install to a blinking LED, and everything after.

1. Install PICPIO

PICPIO is a VS Code extension. Install it like any other:

  1. Open VS Code (free from code.visualstudio.com).
  2. Open the Extensions panel (Ctrl+Shift+X).
  3. Search PICPIO and click Install on the one by CURIOUS WORM.

Or press Ctrl+P and run:

ext install picpio.picpio
PICPIO is self-contained: the build engine, device support and libraries all come inside the extension. Nothing else to download.

2. Add Microchip's free tools

To build and flash real hardware, you also install Microchip's free tools (one time). PICPIO opens the right download pages for you on first run.

  • XC8 compiler: required to build (PIC10/12/16/18). Choose the free license during setup.
  • MPLAB X (IPE + MDB): required to flash and debug over a PICkit/Snap/ICD.
  • XC16: only if you target PIC24 / dsPIC.
The built-in simulator needs none of these. You can write and run logic with nothing but the extension.

Check everything is found anytime by running picpio doctor in the PICPIO terminal.

3. Create a project

  1. Click the PICPIO chip icon in the left sidebar.
  2. Choose New Project.
  3. Pick a name, your chip (e.g. PIC18F27K40), the programmer, and the framework:
    • picpio: the friendly high-level API (recommended).
    • bare-metal: raw registers (TRISx/LATx/PORTx).
  4. PICPIO scaffolds the project: src/main.c, a picpio.ini, and a REFERENCE.md with your chip's pin map and API.

4. Anatomy of a sketch

A PICPIO program has two functions: init() runs once at boot, and run() repeats forever.

#include <Picpio.h>

void init() {              // runs once at startup
  gpio_mode(BUILTIN_LED, GPIO_OUT);
}

void run() {               // repeats forever
  gpio_write(BUILTIN_LED, GPIO_HIGH);
  sys_delay(500);
  gpio_write(BUILTIN_LED, GPIO_LOW);
  sys_delay(500);
}

That's a complete blink program. Pins are named D0–Dn, A0–An for analog, and BUILTIN_LED for the on-board LED.

5. The PICPIO API

Simple, consistent functions across every supported chip:

AreaFunctions
Digital I/Ogpio_mode(pin, GPIO_OUT|GPIO_IN), gpio_write(pin, GPIO_HIGH|GPIO_LOW), gpio_read(pin)
Analog inadc_read(channel) → 0–1023
PWMpwm_write(pin, duty)
Timingsys_delay(ms), sys_millis()
Serial (UART)uart1.begin(115200), uart1.print(...), uart1.println(...)
I2Ci2c1.begin(), i2c1.write(...), i2c1.read(...)
SPIspi1.begin(), spi1.transfer(...)

Example: read a sensor and print it:

void init() {
  uart1.begin(115200);
}

void run() {
  int v = adc_read(A0);     // 0..1023
  uart1.println(v);
  sys_delay(200);
}
Every project's REFERENCE.md lists the exact pin map and the full API for your chip, open it anytime.

6. Build & flash

Use the PICPIO toolbar buttons, or the terminal:

  • Build: compile with XC8/XC16. picpio build
  • Upload: build and flash to your board. picpio upload
  • Upload & Monitor: flash, then open the serial monitor.

Connect your board with a PICkit (or Snap/ICD), hit Upload, and watch it flash:

$ picpio upload
Compiling main.c with XC8...
Program: 3.1%  Data: 1.4%
✓ Flashed to PIC18F27K40
✓ Done in 4.2s

7. Add a library

PICPIO ships 130+ ready-made drivers: OLED/TFT displays, sensors, motor & stepper drivers, RTCs, ADC/DAC expanders, RF/CAN/LoRa, USB CDC serial, GPS/GSM, keypads, SD card (FAT16/32), EEPROM, WS2812 LEDs, servos, PID and more.

  1. Open the Library Manager from the PICPIO sidebar (or run picpio lib add SSD1306).
  2. PICPIO copies the driver in and drops working example code into your sketch.
  3. It also writes the device's wiring + protocol into REFERENCE.md.
$ picpio lib add SSD1306
✓ Added SSD1306 (I2C OLED)
✓ Example inserted into src/main.c
PICPIO warns if a library needs a peripheral (I2C, SPI…) your chosen chip doesn't have, before you build.

8. Simulate before hardware

No board yet? Run your logic in the built-in simulator and watch it work.

  1. Open src/main.c.
  2. Click Simulate in the PICPIO toolbar.
  3. Watch pin states, PWM waveforms, and Serial / I2C / SPI traffic update live as your code runs.

Great for teaching, for checking logic, and for working without hardware in hand.

9. Serial monitor

See live output from your board and send data back:

  1. Click Serial Port Monitor in the PICPIO sidebar.
  2. Pick the COM port and baud rate (match your uart1.begin(...)).
  3. Read incoming lines; type in the box to send data to the board.
COM3 @ 115200
Temp: 24.6 C
Temp: 24.7 C
Humidity: 48%

10. Bare-metal (registers)

Teaching or learning register-level PIC programming? Pick the bare-metal framework when creating a project. You write a normal main() against the chip's real SFRs, with full IntelliSense (autocomplete on TRISB, PORTAbits, …).

// bare-metal blink
void main(void) {
  TRISBbits.TRISB0 = 0;        // RB0 output
  while (1) {
    LATBbits.LATB0 ^= 1;       // toggle
    __delay_ms(500);
  }
}

11. Your project's reference

Every project includes a REFERENCE.md generated for your exact chip:

  • The full pin map (which physical pin is D0, A0, the I2C/SPI/UART pins…).
  • The complete API available on that chip.
  • For each library you add, the device's wiring and communication protocol.

It's read-only and always matches your hardware, keep it open as you build.

12. Troubleshooting

If a build or upload fails, run picpio doctor: it checks your whole toolchain and tells you what's missing:

$ picpio doctor
✓ XC8 compiler   v2.46
✓ PICkit 3 detected
✓ Device pack installed
✓ 130+ libraries
All systems go.
  • "Compiler not found" → install XC8 from Microchip, then reopen VS Code.
  • "No programmer detected" → check the PICkit/Snap is plugged in and MPLAB X is installed.
  • "no device-support files found" → PICPIO downloads your chip's support pack automatically on first build (needs internet). If it can't, run picpio install-dfp once, then build again.
  • Autocomplete missing → reopen the folder so IntelliSense reloads.
Still stuck? Email picpiosupport@gmail.com or visit curiousworm.in.

Install PICPIO   Back to home