Getting Started

This guide walks you from a fresh clone of TikuOS all the way to an interactive shell running on an MSP430 LaunchPad. By the end you will have built the kernel with the shell enabled, flashed it onto hardware, connected over UART, and learned the commands that let you inspect, control, and reconfigure a live device — without recompiling.

Prerequisites

Hardware — an MSP-EXP430FR5969 LaunchPad (primary target) or another supported MSP430FR board.
Toolchain — the msp430-elf-gcc compiler (available from TI or your package manager) and GNU make.
Flasher — mspdebug or TI UniFlash for programming the device over the on-board eZ-FET debugger.
Serial terminal — picocom, screen, minicom, or PuTTY for UART interaction.

1 Clone and Build

Clone the repository and build the kernel with the interactive shell enabled. The TIKU_SHELL_ENABLE=1 flag pulls in the shell process, parser, and command table.

git clone https://github.com/tikuos/tikuos.git
cd tikuos

# Build with the shell enabled (recommended)
make MCU=msp430fr5969 TIKU_SHELL_ENABLE=1

# Optional: ANSI color output for the banner and prompt
make MCU=msp430fr5969 TIKU_SHELL_ENABLE=1 TIKU_SHELL_COLOR=1

A successful build produces TikuOS.out (an ELF image) that can be loaded onto the target.

Tip: Add TIKU_INIT_ENABLE=1 to enable the FRAM-backed boot sequence. This unlocks the init command, which lets you change what starts at boot without reflashing.

2 Flash the Device

Connect the LaunchPad over USB. The on-board eZ-FET debugger exposes both a JTAG programming interface and a USB-CDC serial port.

# Flash using the Makefile shortcut
make flash MCU=msp430fr5969

# Or invoke mspdebug directly
mspdebug tilib "prog TikuOS.out"

3 Connect to the Shell

Open the USB-CDC serial port exposed by the eZ-FET debugger. The default baud rate is 9600; override with UART_BAUD=115200 at build time if desired.

# Linux / macOS — device name varies (ttyACM0, ttyUSB0, cu.usbmodem...)
picocom -b 9600 /dev/ttyACM1

# Or via make
make monitor

Press the reset button on the LaunchPad. The boot banner should appear (shown here with TIKU_SHELL_COLOR=1 — cyan banner, green prompt):

  ___ _ _         ___  ___
 |_ _|_) |_ _  _/ _ \/ __|
  | || | / / || | (_) \__ \
  |_||_|_\_\\_,_|\___/|___/  v0.02
  Simple. Ubiquitous. Intelligence, Everywhere.

  MSP430FR5969  |  SRAM 2048B  FRAM 64KB
  Type 'help' for commands.

tikuOS>

You now have a live TikuOS kernel with a cooperative scheduler, event-driven processes, virtual filesystem, and a shell process waiting for input. Type help to see what's available.

4 Shell Command Reference

The shell groups commands into six categories. Every command is small (kilobytes of flash, zero heap) and most either read or write a node in the virtual filesystem under /sys, /dev, or /proc.

System

Command	Description
`help`	List all available commands, grouped by category.
`info`	Device name, CPU clock, uptime, and reset reason.
`free`	SRAM and FRAM usage — compile-time layout plus live stack headroom.
`reboot`	Trigger a watchdog reset.
`history`	Last N commands, persisted in a FRAM ring buffer across reboots.

Processes

Command	Description
`ps`	List active processes with pid, state, SRAM/FRAM use, and wake count.
`start`	Start or resume a process by name from the catalog.
`kill`	Stop a running process by pid.
`resume`	Resume a stopped process.
`queue`	Show pending events in the global event queue.
`timer`	List active software timers and their remaining ticks.

Filesystem

Command	Description
`ls`	List entries under a VFS directory.
`cd`	Change the working directory within the VFS.
`pwd`	Print the current working directory.
`read` / `cat`	Read the contents of a VFS node.
`write` / `echo`	Write a value to a VFS node.
`toggle`	Flip a binary VFS node (e.g. an LED or GPIO pin).

Hardware

Command	Description
`gpio`	Read, write, or toggle any GPIO pin. Example: `gpio 4 6 t`.
`adc`	Read an analog channel — `adc temp`, `adc bat`.

Power

Command	Description
`sleep`	Enter a low-power mode. Example: `sleep lpm3`.
`wake`	Show which peripherals are currently armed to wake the CPU.

Boot

Command	Description
`init`	Manage FRAM-backed boot entries: `init add`, `init list`, `init disable`, `init remove`.

5 Try It Out

Once the prompt is up, these are good first commands to get a feel for what the shell exposes:

tikuOS> info
Device  : MSP430FR5969
CPU     : 8000000 Hz
Uptime  : 12 s
Reset   : rstnmi

tikuOS> free
--- Compile-time ---
SRAM   2048 total
  .data+.bss   1058
FRAM  65535 total
  code        42508
--- Runtime ---
SRAM
  stack now      80
  free now       910
--- Processes (1/8) ---
 pid  name        sram  fram  state
   0  Shell          0     0  running

tikuOS> write /dev/led0 1
tikuOS> toggle /dev/led0

tikuOS> cat /sys/cpu/freq
8000000

tikuOS> adc temp
Atemp = 1847 (0x737)

6 Reconfigure Without Reflashing

If you built with TIKU_INIT_ENABLE=1, you can change the boot sequence from the shell. Entries are stored in FRAM and survive power cycles.

tikuOS> init add 05 leds  write /dev/led0 1
OK: 'leds' at seq 05

tikuOS> init list
 05  leds         [on ]  write /dev/led0 1

tikuOS> reboot

After the reboot, LED0 comes on automatically as part of the boot sequence — same firmware image, different behavior per device.

Next Steps

Browse the Supported Platforms page for other boards you can target.
Read the API Reference to write your own process using protothreads and events.
See the Architecture page for how the scheduler, VFS, and power manager fit together.
Ask questions or file issues on GitHub.