One Kilobyte Operating System (OKOS)

Tiny computer OS for 1kB challenge.
OKOS is just ok because OKOS is just OK.

Similar projects worth following
Tiny computer OS for 1kB challenge. This is not an embedded RTOS!

Blurring the line between embedded system and general purpose computer. Inspired by all those wizardly tricks that brought computing to the masses on limited hardware.

OKOS is an operating system that allows the user to edit text or assembly source code files, assemble these into executables, and run their programs.

It drives an OLED display and takes input from an capacitive touch keyboard. Files (text, executables) are stored in internal flash.

OS, assembler, editor, and keyboard controller total less than 1k of code including lookup tables, font, and rom.

Source code:

One Kilobyte Operating System (OKOS)

Tiny OS for 1kB challenge.

Blurring the line between embedded system and general purpose computer. Inspired by all those wizardly tricks that brought computing to the masses on limited hardware.

OKOS is an operating system that allows the user to edit text or assembly source files code, assemble these into executables, and run their programs.


  • Runs on a PIC18f25k50, the MCU in the HaD SuperCon Badge!
  • Display driver and API
    • Supports SSD1306 OLED display with 128x64 pixels over i2c, with the font included that is 32x8 characters.
    • Minimal 3x5 tiny font (remember original Apple ][ uppercase only font?)
    • Line buffered text drawing api (write whole row at a time)
    • Optional lowercase font, with descender support 3x5.5! But it takes 10 more bytes to support :(
    • Check out git history for a full ascii compatible font + display driver in less than 400 bytes.
  • Filesystem (if you can call it that)
    • Actually just chopping 32k flash into 16 * 2k files.
    • 15 files available to user numbered 1-F. Can be either text files or programs.
  • Keyboard driver and api
    • PS2 keyboard interface. You probably want an extended keyboard with a numeric keypad (more on that later).
    • Minimal scan code map/table.
    • Keyboard gives you repeat for free.
  • Very basic command line interface lets you edit files, assemble them, and run programs
  • Minimal instruction set assembler for the PIC MCU
    • What kind of OS doesn't let you write code?!?
    • Minimal, but workable, instruction set support.
    • Writes executable machine code into another file. Not interpreted!
  • Visual Text Editor
    • Hopefully better than edlin
  • Run
    • User program takes over
    • Core API available
    • User program interrupts supported (ISR vector depends on what program is running)
  • OKOS is just ok because OKOS is just OK.

One Kilobyte

Code usage by category

Visual Text Editor

Edit a text file with e <file> e.g. e 1 to edit the text file 1.

The current line will have an arrow in the left-side gutter. Arrow keys are not supported, but instead the keypad 8 (up) and 2 (down) keys are used for navigating. You can scroll through the file with these arrow keys.

The cursor is always at the end of the line. You can delete with backspace (including over newlines), or type to add more characters to a line. Pressing enter will append a newline.

Save the file with the F1 key.


Assemble a file with a <source> <out> e.g. a 1 2 assembles source code in file 1 writing the executable to file 2.

Minimal usable PIC instruction set.

3 character mnemonics to save space.

  • ; for comments, can be anywhere
  • . on a line alone to end the file/parsing. REQUIRED

User ISR starts at offset 0x04 or. This gives you enough room to jump away at the start of your program. Boilerplate program with an ISR:

bra 0012 ; jump past ISR
; insert your ISR code here
; ...
bra 000b ; execute a return
; at address 12. insert your code here
. ; EOF

User memory starts at address 0x3A, with the line buffer at 0x1A, anything before that is needed by the core API. If you don't use the API, feel free to reclaim this memory! Note that if you use ISRs, address 0x00 controls which file block the ISR jumps to.

Unfortunately, there wasn't enough room to support labels.

Instruction Set
PIC instructionshort mnemonicargsnotes
bcfbcff, b1 instruction
bsfbsff, b1 instruction
btfscbtcf, b1 instruction
btfssbtsf, b1 instruction
movlwmvlk1 instruction
movwfmvwf1 instruction
movfmvff, d1 instruction
addwfaddf, d1 instruction
andwfandf, d1 instruction
iorwfiorf, d1 instruction
xorwfxorf, d1 instruction
rlcfrlcf, d1 instruction
rrcfrrcf, d1 instruction
gotobrak2 instructions
target address is doubled. Think of them as instruction word addresses instead of byte addresses. File 1 starts at 0x400
callcalk2 instructions. Same addressing as goto
Use bra b

NOTE return is not implemented, but a return instruction is placed at address 0x16 (word 0xb), jumping there will effect a return.

Core API

These API are available and potentially useful to user written programs.

Routineaddresscal addressNotes
Read more »

  • OKOS Capacitive Touch Keyboard

    Ben Hencke12/20/2016 at 03:01 4 comments

    Oooooh, shiny!

    After wrangling Eagle a bit to let me make a regular sized qwerty keyboard, I ended up just using it to draw things and trace an outline and moving the actual electronics to a separate board.

    The controller is made by overlaying a bunch of the circuits before printing the tone transfer sheet.

    The code for the daisy-chained keyboard works, though I had to add 1 more instruction. I've got a "clever" hack, whereby I reuse a portion of the ISR as a subroutine and keep the retfie to both return and re-enable global interrupts. The only problem is that it also corrupts PCLATH with garbage because it isn't an interrupt. You see, normally the interrupt saves a bunch of things in shadow registers before it hits the ISR, and retfie restores all this for you, but in my case the first call is made form main code, and the shadow registers are not yet initialized. Interesting things happen when PCLATH is loaded with garbage right before you try to make a call...

    So 61 total instructions, or 106.75 bytes. That should still leave plenty for receiving.

  • Daisy-chained touch controller in 105 bytes

    Ben Hencke12/19/2016 at 07:31 0 comments

    So it looks like having a PS2 keyboard, while making it easier for anyone to jump in and try this, would potentially disqualify OKOS from the 1k challenge. I can't find any documentation on the controller in my particular keyboard, but there's likely some disqualifying mask-rom microcontroller in it.

    I could just write my own controller for the PS2 keyboard, figuring out how its wired, scan, translate, etc., but I don't really have any code space left to decode AND scan. Plus this wouldn't be nearly as fun or interesting as making something new.

    I've looked at implementing a matrix scan, but don't really care for that. Plus I'd need a pile of mechanical switches. In the end I'd have a keyboard I wouldn't really enjoy typing on without a substantial investment of time. One of the key design drivers for OKOS was a minimal but usable computer, the keyboard has to be usable. For example, I love the idea of the Pocket CHIP, but the bubble-style keyboard is atrocious to use.

    I could do some kind of resistive thing, few parts, simple, but those don't work very well.

    Yes, capacitive touch is what this calls for. I think it will make for a nice, low parts count keyboard.

    Rather than find some chip with 44 touch channels, I can use some chips I already have (PIC16f1574), and take advantage of the 1k rules that allow duplicate code execution.

    So I'm making a daisy-chained touch controller. Each controller handles 8 channels, and you could run up to 32 controllers for 256 channels. OKOS only needs 45 keys, or 6 controllers. The code is only 60 instructions, at 14 bits, thats 105 bytes. Each controller is completely identical and requires no identification configuration, its place in the chain determines it's ID.

    With a bit of wiring, I can make the key and controller placement align naturally with the OKOS charset.

    After removing all of the existing keyboard support, and counting the new keyboard controller code, I'll have 22 bytes left to receive the keyboard data. I think I'll need to borrow the RX uart, which is currently hooked up to the IR receiver on the badge. Putting some tape over it should prevent it from firing spontaneously. It should work!

    Then OKOS will qualify for the 1k challenge! Maybe I'll enter the keyboard controller on it's own :)

  • Working on a test program

    Ben Hencke12/07/2016 at 05:10 0 comments

    I've tested the various components, but it would be cool to have something interesting happen with the whole thing together. So I'm writing a little test program that drives the 74hc138 and sct2024 in the SuperCon badge, enough to blink an LED.

    With a compile flag, it will push some test files to the chip. One is source code, the other is a program assembled by MPLABX of the same program. Then when you boot up the chip, you can start assembling a program without having to type everything in the functional but minimal editor.

    I was able to assemble the source code, get a hex dump of program flash, and verify that the MPLAB compiled code matches the on-chip assembly!

    The LED blinking part isn't working, but hey, everyone has seen blinking LEDs before.

    Here's a quick demo of the editor

View all 3 project logs

Enjoy this project?



Thomas wrote 12/09/2016 at 06:06 point

Nice feat :-) 
In my view, assembler and editor could as well be binary programs loaded from the "file" area, which would free up some space for more OS features. Modern operating systems make a  distinction between the use cases "development" and "normal use cases". You take a similar approach as Chuck Moore with OKAD and colorForth. Moore even blurred the line between source and binary in some occasions.

  Are you sure? yes | no

jaromir.sukuba wrote 12/08/2016 at 19:51 point

Another comment - you may want to be careful with PS/2 keyboards, as those usually do
contain MCU, conflicting with rules. It would be shame to lost this great project from contest. I'm sure you can make support for "bare" keyboard (matrix of switches) in the code space gained from PS/2 support. Or even keyboards from laptops are usable for this task, containing nothing but key matrix.

  Are you sure? yes | no

Ben Hencke wrote 12/08/2016 at 23:34 point

Thanks, good point. I'll see if I can get clarification if a ps2 keyboard is allowed. Might save a bunch of space since I wouldn't need to store keycodes and do any translation!

  Are you sure? yes | no

jaromir.sukuba wrote 12/09/2016 at 08:32 point

I've done some keyboards in the past, one of them with 16F873 in assembly language, just for fun.

Problem with QWERTY keyboard layout is that if you want to keep your hardware straightforward, you end up with "random" raw scancodes, so you have to use lookup table to adjust it into ASCII codes. Though if you arrange 16 keys row in @ABCD.. order, another 16 keys row in PQRST... order, you can easily translate raw scancodes into ASCII just by shuffling few bits in high order nibble of raw scancode.

Then, you have to either leave your keyboard in "ABCDE..." layout (remember Psion 2?) or rearrange it into QWERTY layout, but that's going to make your PCB layout rather messy. In fact, you are going to trade off PCB layout for free space in FLASH.

  Are you sure? yes | no

jaromir.sukuba wrote 12/08/2016 at 19:08 point

Now this is what I call awesome project. I'm reading the code for half an hour now, very clever programming indeed.

Honestly, I'm glad I'm not the only one building pointless computers in tiny MCUs, when there are multi-gigabyte and -gigahertz computers around.

Big thumbs up for this one.

  Are you sure? yes | no

CNLohr wrote 12/07/2016 at 21:21 point

Well, I was going to think about competing... but now...

  Are you sure? yes | no

Ben Hencke wrote 12/08/2016 at 23:37 point

I'd really like to see what you come up with :)

  Are you sure? yes | no

cuzeau wrote 12/07/2016 at 07:48 point

Kudos ! 

I thought I would never see again clever engineering  and struggling for bits and bytes again. Every one even stupid is capable of generating gigabytes of code but a 1k OS forces admiration.

  Are you sure? yes | no

Szabolcs Lőrincz wrote 12/05/2016 at 12:51 point

fun fact: "okos" means "smart" in hugarian.

  Are you sure? yes | no

Does this project spark your interest?

Become a member to follow this project and never miss any updates