Piconomic FW Library  0.4.3 SVN 17
Cross-platform embedded library and documentation for 8/16/32-bit microcontrollers
Piconomic FW Library Documentation

About

The foundation of piconomic-fwlib is knowledge and freedom: the knowledge and freedom to use the right microcontroller for the job and not trying to fit a square peg in a round hole.

piconomic-fwlib is a collection of C firmware and documentation for microcontrollers to develop code that is vendor and architecture independent (or easier to reuse). It is tough to find the best compromise between lean 8-bit targets, middle-of-the-road 16-bit targets, and resource rich 32-bit targets, but this cross-platform library aims to provide a good start before you are forced to add target specific code and getting locked in.

The library (source code and offline documentation) can be downloaded here.

My sincere hope is that seasoned veterans will pitch in and share their years of experience to mentor the future generations and raise the bar in terms of quality and quantity. See Questions or Feedback (please!) .

Goals

  • Provide a standard framework and drivers for rapid code development.
  • Minimize porting by providing unified peripheral driver APIs (to maximize device driver reuse).
  • Publish concise quick start guides and tutorials to reduce the learning curve of new microcontrollers.
  • Share source code, knowledge and expertise with our global community of engineers, scientists and enthusiasts.
  • Recommend good firmware development practices.

Sections

This documentation is divided into the following sections:

Links

Companion Boards

Examples

Here are four examples to pique your interest:

GPIO

This example demonstrates how easy it is to define and use a GPIO pin:

#include "gpio.h"
// LED is on PORT B, pin 2, configured as an output, initally off
#define GPIO_LED GPIO(B, 2, GPIO_DIR_OUT, GPIO_INIT_LO)
// Push Button is on PORT B, pin 0, configured as an input, pull-up enabled
#define GPIO_PB GPIO(B, 0, GPIO_DIR_IN, GPIO_INIT_PULLUP)
int main(void)
{
#if 1
// Initialise group of pins
#else
// Initialise pins individually
#endif
for(;;)
{
// Is button being pressed?
{
// Enable LED
}
else
{
// Disable LED
}
}
}

Even though it appears that functions calls are used, the lines reduce to single assembly statements for maximum efficiency and minimum code size.

C code mixed with generated assembly listing:

// Initialise group of pins
80: 81 e0 ldi r24, 0x01 ; 1
82: 85 b9 out 0x05, r24 ; 5
84: 84 e0 ldi r24, 0x04 ; 4
86: 84 b9 out 0x04, r24 ; 4
for(;;)
{
// Is button being pressed?
88: 18 99 sbic 0x03, 0 ; 3
8a: 02 c0 rjmp .+4 ; 0x90 <main+0x10>
{
// Enable LED
8c: 2a 9a sbi 0x05, 2 ; 5
8e: fc cf rjmp .-8 ; 0x88 <main+0x8>
}
else
{
// Disable LED
90: 2a 98 cbi 0x05, 2 ; 5
92: fa cf rjmp .-12 ; 0x88 <main+0x8>

For IoT low power sensor nodes it is extremely important to wake up, do something as fast as possible and go back to sleep again. C efficiency trumps C++ flexibility. Less code translates to a cheaper solution.

UART

This example demonstrates how easy it is to set up and use a UART peripheral. After the set up phase (using architecture specific options), the driver is abstracted and the same code can be used on different architectures:

#include "uart.h"
#include "common/compiler.h"
static uart_handle_t uart_handle;
int main(void)
{
u8_t data;
// Initialise modules
// Enable interrupts
interrupts_enable();
// Open UART0 @ 115200 BAUD, 8 data bits, no parity, 1 stop bit
uart_handle = uart_open2(0,
115200,
UART_DATA_BITS_8,
UART_PARITY_NONE,
UART_STOP_BITS_1);
// Select UART0
uart_select(uart_handle);
for(;;)
{
// Wait until a byte is received
if(uart_rd_u8(&data))
{
// Send back received byte (loopback/echo mode)
uart_wr_u8(data);
}
}
}

CLI (Command Line Interpreter)

This example demonstrates a CLI (Command Line Interpreter) that creates a "Linux Shell"-like environment running on the microcontroller so that you can experiment with GPIO, ADC, I2C and SPI using only an ANSI/VT100 terminal emulator (for example Tera Term).

tera_term_cli.png
CLI Demo on Tera Term (Terminal Emulator)

Defining commands and using the CLI module is easy (I hope)

Data Logging

log_fs is a simple (but robust!) record-based file system to log data to AT45D DataFlash (or other similiar flash storage). It is perfect for IoT (Internet of Things) low power sensor nodes that need to log data periodically, because it can handle power loss gracefully, requires less code and data memory and executes quickly which means you can get away with a smaller, cheaper microcontroller.

A section of the external AT45D DataFlash can also be reserved for secure "over-the-air" encrypted firmware upgrades.

Usage example:

#include <stdio.h>
#include "board.h"
#include "spi.h"
#include "devices/mem/at45d.h"
#include "data/log_fs.h"
typedef struct
{
s32_t temperature;
s32_t pressure;
static spi_handle_t at45d_spi_handle;
static log_fs_time_stamp_t time;
static log_data_t log_data;
int main(void)
{
const log_fs_record_t * record;
const log_data_t * record_data;
// Initialise modules
at45d_spi_handle = spi_open2(BOARD_SPI_CS_AT45D,
at45d_init(at45d_spi_handle);
// Initialise file system
// Set file creation time
time.year = 15;
time.month = 12;
time.day = 28;
time.hour = 0;
time.min = 0;
time.sec = 0;
// Create a new log file
log_fs_create(&time);
// Populate data
log_data.temperature = 230; // 23.0 deg Celsius
log_data.pressure = 100000; // 100 kPa
// Write record
log_fs_record_wr(&log_data, sizeof(log_data));
// Read first record
while(record != NULL)
{
// Display record data
record_data = (log_data_t * )record;
printf("%ld\t%ld\n", record_data->temperature, record_data->pressure);
// Read next record
}
}

For a complete working example (with nice flash file system debugging), see Temp&Pressure Data Logger Application.

log_temp_pressure_graph_preview.png

Evolution

Great athletes spend years tweaking tiny aspects of their performance to get a competitive edge: bicycle riders adapt their posture in a wind tunnel, golfers analyse their swing,... Like the shark became the apex predator of the sea, we as coders must be inspired to evolve and perfect our art or wither.

Without mentorship, we tend to get stuck with the first coding style and programming patterns that we learned and keep on using it without a second thought, sometimes even justifying and defending it religiously.

After you have written a piece of code, take a break, return and spend 15 minutes to question if the code you have just written is the optimal / best / most readable solution (applying advice from Edward de Bono, the father of lateral thinking). Refactor, rinse, repeat. Next time you will use this improved snippet instead of copying and adapting the same old, inferior code from memory.

Ask yourself: which is better?

// Small fixed delay
for(i=0; i<100; i++)
{
__asm__ __volatile__("nop \n\t"::);
}

Or

// Small fixed delay
for(i=100; i!=0; i--)
{
__asm__ __volatile__("nop \n\t"::);
}

Inspect the assembly generated by the compiler...

Evolve, improve or be left behind!

Editor

As artisans that code for food, we must buy and use the BEST editor, like SlickEdit, not the low budget / free one that we got used to. Think it through! If you use an editor every day to ply your trade and a better editor saves you just 5 - 15 minutes a day, then it will be the best personal tool investment you ever made and it will give you a legal edge over your colleagues and competitors. You don't know what you are missing! Try the evaluation version for the whole 30 days before dismissing my advice. I am confident that SlickEdit will make a massive improvement in your productivity!

I have been discovering and using cool SlickEdit features since 1999.

License

This library requires time and money to improve and grow (neither of which is free). Despite this, an extremely lenient and fairly priced licensing model was selected to support both open or closed source (commercial) development. If you think it is unfair in any way or are discouraged from using or contributing to the library, PLEASE LET ME KNOW! See Questions or Feedback (please!) .

To comply with clause 3 of The Piconomic FW Library Open License, the following text and URL must be added to all internet publications (including advertisements) of your project or product:

Uses Piconomic FW Library <http://piconomic.co.za>

A significant amount of time and effort has been invested to create, publish and refine this library. Respect the license conditions!

A single developer commercial license or company commercial license can be purchased which will grant you or your company an exemption from clause 2 and 3 of the The Piconomic FW Library Open License. The proceeds will be used for the continuous development and refinement of this library, hosting costs, etc. For more info, please read the FAQ .

CLICK HERE TO VISIT THE SHOP

Roadmap / Wish list

  • Microchip PIC24F support (in progress...)
  • ARM Cortex-M support (in the future)
  • Videos
  • Project configuration wizard to configure Makefile, GPIO and other modules (written in Qt to run on Windows, Mac and Linux).
  • Graphics Library (lines, rectangles, circles, bitmaps, fonts, ...)
  • Graphics Library WYSIWYG IDE (written in Qt to run on Windows, Mac and Linux).
  • FAT File System Library for SD Cards (SD Card driver finished; see sd.h : SD Card Driver).

Questions or Feedback (please!)

There's no such thing as a stupid question (only stupid answers?). A question posed is an opportunity for me to improve the library, because it will highlight areas that are unclear or difficult to understand.

Like it? Hate it? Think it has no value? Clear or confusing? Language too simple or too sophisticated? Pitched too low or too high? Either way, PLEASE send me a short (or long) message to let me know what you want or think so that I can try to improve the library and companion boards. Your brutally honest feedback (positive or negative) is vital to me so that I know if I'm on the right track or not.

feedback.png

Methods of communication:

  • Forums (if the answer to your question may benefit other users too)
  • Contact page
  • E-mail:

I respect your privacy and won't divulge or use your contact details for any purpose without your explicit permission.

If you submit new code or a bug fix (please do!), it must:

To be clear: when you submit any new code, you also give me explicit permission to sell an exemption to clause 2 and 3 of The Piconomic FW Library Open License and use the funds to take over the WORLD! Bwah Ha Ha!! Ahem... Joking aside, why would you want to contribute new code or bug fixes if you don't benefit financially? When the library achieves critical mass, you will benefit from an extensively tried and tested ecosystem.

Share and Enjoy!

Author

pieter_conradie.jpg
Pieter Conradie