= CasiOS Developer Guide
:toc: left
:toc-title: CasiOS Dev Guide
include::attributes-urls.adoc[]

This document is meant as reference for developers interested in the firmware
running on the PowerPIC -- *CasiOS*.


== Building CasiOS

=== Software Prerequisits
A few programs are required to build the firmware:

`make`::
Make is required for the `make` command. It should be installable from your
distro's package manager.

`xc8-cc`::
The firmware is compiler with Microchip's xc8 compiler. It can be downloaded
{link-xc8-dl}[from their website] for all operating systems. If you use Arch
Linux, an AUR package is available: {link-xc8-aur}[microchip-mplabxc8-bin].


== CasiOS Framework

The CasiOS framework provides developers with both low level drivers and higher
level libraries. The drivers provide access to all of the underlying hardware.
However, it is recommended to use the available libraries which give a better
interface and prevents several issues.

// === Creating a new Mode

=== Events

CasiOS is event based, meaning that events are emitted by various modules such as ticks, buttons, keypads, and alarms. The mode in the foreground and all daemons are passed these events so they can act on them.

Events are 16-bit integers with the high byte representing the event type and the low byte representing the event data.

=== Libraries

CasiOS libraries should be the primary way modes interact with the hardware.

==== display.h
_Library for drawing to the segmented display._

The display library splits the display into 5 groups:

* *Primary* + 
The primary display consists of the 8 main 7-segment characters. This allows
displaying a string of max 8 characters, an integer ranging from 99,999,999 to
-9,999,999, or a hex number from 0x0 to 0x7FFFFFFF.

* *Secondary* +
The secondary display is the 2-character group in the top right of the display,
used to display the day-of-week in the stock Casio firmware. These two characters
contain a few extra segments that allow a wider variety of characters and
numbers. Because of these we can display a better "M", "W", "T", "I" at
position 1, and a better "T", "R" at position 2. These extra character also
allow us to display a 1 in the hundreds place, which means we can display
numbers -9 to 128, and 0x0-0xFF.

* *Punctuation* +
The punctuation display includes the periods separating each character in the
primary display and the colon in character position 3. 

* *Signs* +
The sign display is the 4 arithmetic sign segments: +, -, *, /.

* *Misc* +
The misc display includes the AM and PM segments, the alarm segment(vertical
lines), and the signal segment(bell).


==== alarm.h
_Library for managing alarms._

An alarm in CasiOS emits an event ID at a specific time and date.
An alarm event ID is an integer with the high byte set to the alarm event ID (0x0A) and the low byte set to the alarm ID passed when creating an alarm.



=== Drivers

CasiOS drivers are a thin layer between libraries and the hardware. They should not normally be needed, but can be used if care is taken.

==== lcd.h
_Driver for the liquid crystal display peripherial._

The LCD peripherial provides us with a bank of registers that map directly to
segments on the display. Each bit represents a single segment. This driver
provides a working buffer that is equal to the size of the LCD segment
registers. Upon a call to `display_update()`, it will copy the values from the
working bufffer into the segment registers.

---
[.text-center]
[.big]#{link-powerpic-github}[github] | {link-powerpic-docs}[documentation] | {link-powerpic-home}[website]# +
&copy; 2025 Rex McKinnon <[email protected]>