The CyBorn Project

The aim of these wiki pages is to help document and gather information that will be used to get the Cyborn project up and running.

The sourceforge home page for this project is http://sourceforge.net/projects/cybiko-reborn/

The Cybiko is a PDA with interesting provisions for updating. The idea behind the Classic Cybiko was that it could be programmed and programming by the users was encouraged and supported by the company that made it. The SDK was provided free of charge. Later a 'professional' edition was released. The hope of real tools to program the Cybiko were not met. This is the impetus and desire behind 'Cybiko Reborn.'

This Operating System (OS) will contain the 'personality' for the Classic Cybiko. The old CyOS had similar functions, but were implemented in different ways. For example, the audio system on CyOS was a simple tone generator. CyBorn will have a similar function, but different 'personality': a PWM drive and be capable of simple sounds (8K mono wav).

Cybiko Reborn - CyBorn

The new OS will be general purpose targeting everything from games to chat to technical. The most unique and interesting feature of the Cybiko is the built in wireless RF communications and the serial port connection to the PC allowing it to bridge remote cybikos to a PC. To that end we will focus on perfecting the following functional areas:

  • Serial interface to/from PC targeting 115K BAUD
  • RF communications - fast and robust
  • RF networking - mesh networking

In addition, the CyBorn OS will need several things to be a complete OS:

  • Kernel
  • Libraries
  • System Task
    • Application shim
  • Filesystem
  • Hardware interfaces
    • Audio system
    • Display system
    • Communications system for both serial and RF
    • Keyboard input
    • Vibrator motor
    • LEDS
    • Real Time Clock
    • Expansion port
  • BootMonitor - this is built in to the Cybiko's ROM and will be reused during startup.
  • Flash programmer / OS loader.

The kernel is the heart of the operating system. It will provide the following services:

  • thread services
  • signal services
  • message-passing services - the kernel will handle all routing of messages between threads throughout the system.
  • synchronization services
  • scheduling services - the kernel will schedule threads for execution.
  • timer services
  • process management services - the process manager is responsible for managing processes, memory and the pathname space.
  • Monitors battery level
  • Controls charge circuitry
  • Monitors Network Mesh
  • Audits System integrity
  • Provides 'shell' for application execution environment
  • Gathers all events and pre-filters for system events (special keystrokes)

Application Shim (other name?)

Need a selector and loader for applications. The system task will provide a way to select an application (GUI or text). The application shim needs to load the selected app into memory and hook up the event queue, resources, etc..

Event Manager (other name?)

Filters system and user events to the application. The current application gets the keyboard input. Some events will follow the app that registered for them - timers for example.

The Libraries should have as many useful functions as possible since there is not much memory available to store programs in. Some trial programs should be written to determine what functions need to be put in the library to cover the most common (and maybe not common, but bulky) functions.

The libraries will be stored in the flash memory along with the OS. There will be a jump table to all functions so that when loading a new version of the OS, all programs do not have to be recompiled to find the function entry points.

Standard/Common Library

This library will include most standard functions found in the 'C' language: strings, memory, etc. There will be some additional functions that are simple and specific and usefull to the cybiko.

Fixed Point Math

There are two options for implementing a fixed point maths library.

  • 8.8 - Fast
  • 32.32 - Precise

The basic trade off is between reponse and precision. By implementing two separate library the decision can be made by the developer as to what would be acceptable for their application.

References

Graphics Library

The graphics library is for lowlevel/primative/intermediate operations. Other libraries should build on these primitives. These primitives will be optimized for speed by using assembly language and/or algorithm choice and/or architecture exploits.

Primitives include: line, box, rect, circle, oval(ellipse), sprites. Intermediats include: surface, fonts. The surface is always sized in bytes wide and is byte aligned to the LCD display. This allows for quick updating to an area of the LCD when needed (like a game score).

Two kinds of fonts are supported: scalable and bitmapped. The Scalable font is limited to only capital letters and numbers - OK for scores and announcements, but annoying for lists, etc. Bitmapped fonts look great, but take up alot of space and are limited to a single size per font although some kinds of programming tricks can make fonts appear bold by rendering at a pixel offset off one in the horizontal or vertical (kind of like the old dot-matrix printers did for emphasized and enhanced modes). The bitmapped fonts could be stretched to double-size making an 8×6 become 16×8, etc.

Time Library

The Cybiko has a built in Real Time Clock (RTC). The RTC keeps time and date independantly of the H8 running. The RTC time and date can be set and read. There is also an alarm that can be set. The RTC alarm output is connected to the power-up circuitry and interrupt and can be used to wake the Cybiko up out of a 'sleep' state. Design notes: the RTC is connected via I2C interface and needs to be 'bit-banged' to be accessed. It may be best to read the RTC every hour (and at startup) and set a counter in an interrupt that keeps time? Be carefull with this chip - if something in the alarm registers gets messed up there may be a chance that it will lock the cybiko by continually reseting.

API: RTC_GetTIme, RTC_SetTime, RTC_GetDate, RTC_SetDate, RTC_GetAlarm, RTC_SetAlarm, RTC_EnableAlarm, RTC_DisableAlarm, etc.

DataSystem Library / API

The datasystem gives access to the data stored in the dataflash that is onboard and on the expansion card (if present). If there is leftover room in the OS flash then access could be provided for additional storage. Other storage mediums could be added: more serial flash, compact flash, etc.

Requirements:

  • Provide for multiple data sources open at once.
  • Provide some kind of directory structures.
  • Compatible with any standards? FAT? or make proprietary - fast and compact?

File operations API: DataOpen, DataClose, DataRead, DataWrite, etc

FileSystem operations API: remove, create, rename, etc

Game Library

Support for things found in games - graphics for cards?, scoring, moving sprites, 3d extensions.

Messaging Library

Some kind of mesh networking - API could abstract communications medium (use RF, or use serial if connected to internet, etc)

GUI

Library for making and presenting dialogs and marshalling data from dialog to structures, etc. Includes: List, buttons, etc…

Compatibility

With the creation of a cybiko (VCC) compatible library existing programs could be ported to the new operating system without having to be rewritten.

This compatibility library would implement all of the existing cybiko SDK within the new operating system environment.

The Cybiko has data flash memory that is used for storing program and data files. The Cybiko OS (CyOS) allowed only files and no directories. CyBorn will have directories, but limited to about 120 max. This is a good trade off by allowing directories, but not the complication of extended entries for unlimited directories.

The interface to the data flash is a simple serial IO connection. The ready/busy line connects to the wait line of the Atmel processor. While writing to flash, there can be a delay of up to 20ms where the processor is stopped. The CyBorn project will not use the wait state, but have interrupts set to start waiting tasks.

The built in flash device is from Atmel. It is 4Mbits arranged as 2048 pages of 264 (256+8) bytes. The device has two buffers that can be used for reading or writing. For reading only, the main memory can be read directly without need to use the buffers. The buffers must be used for writing; either writing through them in one operation, or writing to a buffer and then commanding the buffer to be written to the main memory.

Reading the flash can be done without using the buffers in the flash device. Before reading from the flash device, the filesystem needs to be searched for the file open for writing and looking if the requested page is being written to in another files write buffer. If it is, use the data from the write buffer, otherwise, read the data from the flash device main memory. If there is another file descriptor with write access, make sure that a write of more data to that page does not occur before reading of that page is finished - maybe turn off pre-emption.

Filesystem Requests

The file system can be implemented as a message-based system service. It also provides the shared access required for a true multitasking system. The file system will actually run as a separate task.
What do you think?

File system services

Function Description
OpenFile opens an existing file in the current path. A full file specification may be provided to override the current job path
CloseFile closes a file that was previously opened.
ReadBytes This reads one or more bytes from a file.
WriteBytes This writes one or more bytes to a file. The file must be opened in Modify mode.
Seek Moves the File Access pointer
GetFileSize This gets the current file size for files opened in any access mode.
SetFileSize This sets the current file size. The file length, and allocated space, will be extended or truncated as necessary to accommodate the size you specify
CreateFile This creates a new, empty file in the path specified. The file is closed after creation, and ready to be opened and accessed.
RenameFile This renames a file. The file must not be opened by anything in any mode.
DeleteFile This deletes a file from the system. No further access is possible, and the filename is available for re-use. The file must be opened in Modify mode (which grants exclusive access).
CreateDirectory This creates a new, empty directory for the path specified. The path must contain the new directory name as the last element. This means all subdirectories above the last directory specified must already exist. If only the new directory name is specified, as opposed to a full path, the directory is created in your current path.
DeleteDirectory This deletes a directory for the path specified. The path must contain the directory name as the last element.

File Specifications

A filename consists of one to eight characters, a period, then up to three more characters. For exmaple, filename.txt

A full file specification will consist of a drive letter identifier followed by a colon, then the path - which is each directory separated by the blackslash character - any finally the filename itself. for example:

     a:\Dir1\Dir2\Dir3\Filename.txt

This is MS-DOS naming nomenclature but I'm up for something better - perhaps just 32 characters of free format characters.

Network File Request Routing

File system requests are routed based on the full file specification. A filename that is prefixed with a node name will be routed to the service with the same name. A full network file specification consists of two parts:

  1. The first part is Node name enclosed in braces {}.
  2. The second is the filename as described above. A complete network filename looks like this:
   {Node}a:\Dir1\Dir2\Filename.txt

When a network file is opened, the network service receives the request from the file system. The filehand that is returned will be unique on the system that originated the request.

The filename across a network may not be limited to the MS-DOS file naming conventions described above. This depends on the type of file system on the node being accessed.

File Handles

When a file is opened, in any mode or type, a number called a file handle is returned to you. The file handle is used in all subsequent file operations on that file. This number is how you refer to that file until closed.

File Open Modes

A file may be opened for reading and writing, or just reading alone. These two modes are called modify(Read and Write) and read(Read-only).
A task is granted exclusive access to the file whilst it is opened in Modify mode.
Multiple tasks may open and access a Read-only file. When a file is opened in Read mode, it may not be opened in Modify mode by any other task.

When a new OS is created and ready to load, a separate program needs to load first into RAM and execute. Its purpose is to receive the OS from the serial port and flash it into the FLASH memory. The program is discarded and not needed again until the OS needs to be updated/loaded. The new OS will be started by the built-in monitor ROM at the next system start.

There are two ways of getting a program into cybiko flash:

  1. Write a bootstrapper program that can access the flash memory and have the OS piggy back as data onto this bootloader.
  2. Figure out how the cybiko monitor program interacts with the serial port to receive and flash a new OS. This is the method that is used by Cybikos factory reset utilities.

Audio

The audio system on the Cybiko Classic is very limited. It is comprised of a single port pin output that connects to a capacitor that drives the base of the driver transistor. This can easily produce tones, because the port connects to a timer output. It is difficult to do PWM, because the capacitor removes the DC component and makes true integration difficult.

Communications

RF

The RF system uses a ATMEL coprocessor to accomplish transmission and reception of the RF packets. Data transmitted by this sub-system is manchester encoded and it is assumed that the encoding is being performed by the coprocessor. The H8 CPU communicates with the AMTEL AVR chip using a bit-banged interface operating at 53.3k baud, as identified by reverse engineering the coprocessor internals see Firmware AVR. The exact nature of this communication protocol is at this stage unknown.

RS-232

The serial connector can be connected to a PC. If the OS can't keep up with the incoming data rate, flow control is needed. As hardware DTR/DSR pins are not provided on the rs232 connector any flow control implemented will have to be protcol based.

Keyboard input

The keyboard is scanned by outputting columns and reading rows. The only key that is interrupt driven is the 'esc' key, this drives IRQ 1. The other keys must be polled. CyBorn uses a periodic interrupt to scan the keys at a set interval. The scanned keystroke is entered into the system queue for processing.

The keyboard will be handled with a system service. It is a service because it is a shared resource just like the filesystem. Several programs can have an outstanding request to the keyboard service at one time. Only one program (job) will be assigned to receive keystrokes at any one time. The exception to this rule will be the Global Keyboard requests (Fn-key and ESC).

Display

The 4 gray scale display has 160 dots across and 100 dots down. Each dot consumes 2 bits so one line uses 160 * 2 bits = 320 bits = 40 bytes. 40 bytes * 100 rows = 4000 bytes for the entire display. The driver chip has 4000 internal bytes of display memory. Access to the display memory is through registers in the display chip; the display memory is not mapped to memory space. While writing via registers, there is some help with auto-increment of either rows or columns to help get the data into the driver chip.

Graphics

Graphics that are bit mapped are made of of memory that has been pre-created; i.e. a smiley face. Another 'paint' type program has been used to make the face. Now the face can be copied to the display memory to make a face. The other type of graphics are compute graphics. The graphic is computed and then drawn. The computed graphic can be drawn into an empty bitmap and then used like bit mapped graphics.

There are many ways to write graphics to make a display. One is to have an array that represents the entire display and write to it and then copy the display array to the memory in the display chip; this is fast, but uses 4K of memory. Another way is to read and write the display chip memory; this is slow, but uses little memory. A hybrid way of access is to clear the display chip memory (fast and little memory) and then only use 'sections' of the screen to write to. These sections are byte aligned so that moving and copying sections are fast and since only the desired section is used, memory can be conserved.

LEDS

There is a two colour LED: red/green.

Vibrator

Since the circuit in the Classic Cybiko does not protect against back EMF, the vibrator should not be used. Some kind of API will be provided.

Power Control

The Cybiko has 2 NiMh batteries. The ADC on the H8 monitors the battery voltage and can actuate the charge enable circuit. CyOS (the original OS) did not monitor the battery when the Cybiko was powered off - Cyborn needs to be able to power down and then wake up and check periodically for charging the battery.

Expansion Port

The expansion port can accept more RAM and dataflash. Since address lines and chip selects are available, other devices could be mapped and used when connected to the expansion port.