What is this?

This repository is a 'batteries-included' template for projects using 8bit PIC microcontrollers from Microchip. The primary development of this setup has been using the PIC18FxxK42 family, but many of the features should be applicable to other 8 bit PICs(PIC10, PIC12, PIC16).

Getting Started

Make sure the requirements are satisfied, then run the following commands:

git clone --recursive https://github.com/DaelonSuzuka/K42-Project-Template
cd K42-Project-Template
make compile

You can also fork this project, then create a new repository and select K-42-Project-Template from the Repository template drop-down box. Unfortunately, GitHub templates do not preserve git submodules, so after you create your repo from the template, you'll need to manually add the submodules:

git clone <your repository URL>
cd <your new repo directory>
git submodule add https://github.com/DaelonSuzuka/K42-Peripheral-Libraries.git src/peripherals
git submodule add https://github.com/DaelonSuzuka/K42-System-Libraries.git src/os
git submodule add https://github.com/DaelonSuzuka/Easy-XC8.git toolchain

You should then commit your changes and push them back to GitHub.

Requirements

• GNU Make (Tested with 3.8.2 and 4.4. Others probably work, but haven't been tested)
• python3 >= 3.6 (including the venv and pip modules)
• xc8 compiler (xc8 must be on your path)
• mplabx IPE (ipecmd or ipecmd.sh must be on your path)

Features

Easy XC8

Easy XC8 is a no-hassle toolchain that frees you from the shackles of MPLABX IDE.

Features:

• editor agnostic (I recommend Visual Studio Code)
• build your project
• upload your hex file using an attached USB programmer
• in-line code generation using Ned Batchelder's Cog and my CogUtils and CodeGen libraries
• creating documentation with Doxygen
• static analysis using Cppcheck, and possibly clang-analyzer in the future

K42 Peripheral Libraries

This repository has drivers for the following peripherals:

• Analog-to-Digital Converter
• Configurable Logic Cells
• Device Information Area
• Fixed Voltage Reference/Temperature Indicator Module
• High/Low Voltage Detect
• Interrupt
• Nonvolatile Memory
• Oscillator
• Ports
• Peripheral Pin Select
• Reset Handler
• Timers
• UARTs

K42 System Libraries

The following system libraries are included:

• Serial Port, a UART wrapper that provides getch(), putch(), print(), and println(). defining putch() enables XC8's printf()
• Stopwatch, provides calibrated millisecond and microsecond stopwatches, and helper macros to help with profiling your code
• System Clock, a calibrated, 1ms resolution central clock, delay_us(), delay_ms(), get_current_time(), and time_since()

Included files

Additionally, a selection of example files are included.

• Makefile, generated with the toolchain's install script
• project.yaml, generated with the toolchain's config wizard(make config)
• cogfiles.txt, the list of files to be processed by make cog
• pins.csv, this file defines all the pin settings, see Pin Configuration
• src/main.c,
• src/config.h, a reasonable collection of configuration bit settings
• src/pins.c, see Pin Configuration
• src/pins.h, see Pin Configuration
• src/system.c,
• src/system.h,

Startup

TODO: Walk through startup() and the proper sequencing of xxxx_init()s.

Pin Configuration

Pin configuration code in src/pins.c and src/pins.h is generated by embedded blocks of python code, powered by Ned Batchelder's Cog. The actual code generation is handled here.

Pin configurations are defined in pins.csv. The example code has two pins defined:

B0, DEBUG_TX_PIN, output pps
B1, DEBUG_RX_PIN, input pps

This causes the following code to be generated in pins.c:

// GPIO read functions
// none

// GPIO write functions
// none

void pins_init(void) {
  // DEBUG_TX_PIN
  TRISBbits.TRISB0 = 0;

  // DEBUG_RX_PIN
  TRISBbits.TRISB1 = 1;
}

And the following code to be generated in pins.h:

// GPIO read functions
// none

// GPIO write functions
// none

// PPS initialization macros
#define PPS_DEBUG_TX_PIN PPS_OUTPUT(B, 0)
#define PPS_DEBUG_RX_PIN PPS_INPUT(B, 1)

// ADC Channel Select macros
// none

These PPS initialization macros are then used in system.c to configure a UART for the serial port:

uart_config_t config = UART_get_config(2);
config.baud = _115200;
config.txPin = PPS_DEBUG_TX_PIN;
config.rxPin = PPS_DEBUG_RX_PIN;
serial_port_init(UART_init(config));

TODO: instructions for adding your own pins