Python SDK reference

Every call a Python app can make, with parameters, return values, remarks and a working snippet for each. The app model itself is on Python apps; the machine-readable stub ships on the device as SDK\uno.pyi.

The application object

A Python app is one .py file that defines a class and a module-global instance named exactly app. The runtime (PYRT.UNO) executes your file top to bottom, looks up app, and binds whichever of the six callbacks you defined. There is no event loop to write and no main(): the desktop calls you.

import uno

class MyApp(uno.App):

    def build(self, cv):        # once, when the window opens
        self.w, self.h = cv.width(), cv.height()

    def draw(self, cv):         # every repaint
        cv.clear(uno.rgb(16, 18, 34))
        cv.text(8, 8, "hello", uno.rgb(214, 218, 232))

    def tick(self):             # ~60 times a second
        return False            # nothing changed - let the shell sleep

    def key(self, uni, scan, ctrl):
        return False            # not ours - let the shell have it

app = MyApp()                   # the runtime looks for this exact name

Callbacks

Key codes

Keys the shell owns never reach you: Ctrl+Esc, Alt+Tab, Ctrl+W, Ctrl+M, Ctrl+Tab, F2, Alt+arrows, and Esc while a popup or fullscreen app is up.

The idle idiom

An app that returns None from tick() repaints sixty times a second whether anything changed or not. A static app should keep a dirty flag instead:

def key(self, uni, scan, ctrl):
    ...change something...
    self.dirty = True
    return True

def tick(self):
    if self.dirty:
        self.dirty = False
        return None                 # repaint this frame
    return False                    # idle - skip the repaint

Canvas

The drawing surface handed to build and draw. Coordinates are canvas-relative - (0, 0) is the top-left of your content area, below the title bar - and draws are clipped to your window. All coordinates must be ints: pass int(x) if you animate with floats, or the call raises TypeError.

The remaining Canvas methods (wall_col, wall_span, mask_span, flat_span, duum_frame, seg_cols) are the textured-column fast paths built for Duum's renderer; their exact contracts are in SDK\uno.pyi.

uno.rgb

uno.rgb(r, g, b) -> int packs three 0-255 channels into the colour value every drawing call takes. Build your palette once at module level, not per frame.

RED = uno.rgb(255, 96, 96)      # channels are 0-255, masked & 0xFF
cv.fill_rect(10, 10, 40, 40, RED)

Time and held keys

uno.ticks() -> int - the Toolbox tick counter. Honesty first: this is a call counter shared with every C app (it advances once per call, from anywhere), so treat it as frame pacing only - call it exactly once per tick() and use deltas - or skip it and count your own tick() invocations. For real time, use unoauto.uptime(): milliseconds since boot, ungated in every build - the clock the automation samples pace on.

import uno, unoauto

def build(self, cv):
    self.frames = 0                     # your own frame counter...
    self.t0 = unoauto.uptime()          # ...and the real clock, in ms

def tick(self):
    self.frames += 1                    # ~60/s: fine for animation pacing
    elapsed_s = (unoauto.uptime() - self.t0) // 1000   # honest seconds

uno.keys_down() -> int - the navigation/action keys held right now, as a bitmask: 1 Up, 2 Down, 4 Right, 8 Left, 16 fire (F or Ctrl), 32 use (Space/E), 64 comma, 128 period. For movement, polling this beats buffering key() events.

held = uno.keys_down()
if held & 1:  self.y -= 2           # Up is held right now
if held & 4:  self.x += 2           # Right
# 0 on the firmware input path (no key-up events there):
# fall back to timing out your own key() events, like Duum does.

Sound

uno.beep(midi, ticks) plays a square-wave note at a MIDI pitch (60 = middle C, 69 = A440) for ticks sixtieths of a second; uno.quiet() stops it. These two always work, on any machine.

uno.beep(69, 30)                    # A440 for half a second
uno.quiet()                         # cut it short

The sampled-audio calls need a DAC (HD Audio or AC'97) and raise OSError when the machine has none - always wrap them and fall back to beep:

try:
    ok = uno.sfx_load(0, pcm_bytes, 11025)   # slot, 8-bit PCM, rate
    uno.sfx_play(0, 200, 128)                # slot, volume 0-255, pan 0/128/255
    uno.mus_play(smf_bytes)                  # standard MIDI file; loop=1 repeats
except OSError:                              # no DAC on this machine
    uno.beep(60, 10)                         # the square wave always works

Files

Volumes are numbered; 0 is the boot volume and the one-argument forms default to it. Names are 8.3 on FAT volumes and case-insensitive. There is no listdir and no file objects - the API is whole-file and offset reads, which is what a small app actually needs.

data = uno.read("NOTES.TXT")        # the boot volume; None if missing
big  = uno.read(1, "DATA.BIN")      # an explicit volume index

# stream a large file instead of loading it whole:
hdr = uno.read_at(0, "GAME.WAD", 0, 12)     # vol, name, offset, length

n = uno.size("NOTES.TXT")           # -1 if it does not exist

ok = uno.write("SCORES.TXT", text.encode())
if not ok:
    ...                             # read-only volume - tell the user

uno.mkdir("SAVES")                  # one level; the parent must exist
uno.write("SAVES/SLOT1.DAT", blob)

Preferences and key bindings

Small per-app settings without inventing a file format: uno.pref_get(name) -> str|None and uno.pref_set(name, value) -> bool persist strings (values capped at 32 bytes) in the shell's preference store. uno.bind_name(action), uno.bind_set(action, uni, scan) and uno.bind_reset() read and remap the shared game-action key bindings.

name = uno.pref_get("player") or "YOU"   # None on first run
uno.pref_set("player", name)             # values are capped at 32 bytes

The system log

uno.log(sev, fac, text) writes a line to the system log (severities follow syslog; fac is a numeric facility - apps are 6). The viewer app, the log file sink and the remote link all see it - prefer this to inventing your own trace file. The reading half (log_read/log_span/log_stat/...) is documented in SDK\uno.pyi.

uno.log(6, 6, "level loaded")   # severity, facility, text - both ints
# severities follow syslog: 3 err, 4 warning, 5 notice, 6 info, 7 debug.
# facilities: 0 kernel, 1 net, 2 storage, 3 browser, 4 ui, 5 security,
# 6 app (yours), 7 remote.  Read it back in the System Log viewer.

Hardware introspection

uno.devices() -> str and uno.pci() -> list expose the device tree (location, IDs, class, claiming driver) - the same data the devices remote verb reports. Read-only.

Language and library limits

The runtime is MicroPython at its core feature level, plus the modules above. What that means in practice:

unoauto: drive the machine

import unoauto is the automation half of unoautomate, available to any Python app in every build: each call checks the caller's privilege and, when the capability is absent, returns its inert value (False, [], None) instead of raising - so the same script degrades gracefully on a machine that trusts it less. uptime() and deadline_left() are ungated.

The load-bearing pattern - actions land on the next shell frame, so run your steps from a generator and yield between step and check:

import uno, unoauto

class Bot(uno.App):
    def build(self, cv):
        self.steps = self.script()
        self.until = 0

    def script(self):
        unoauto.key(0x17, 0, 1)     # Ctrl+Esc: open the Start menu...
        yield 30                    # ...which lands on the NEXT frame
        unoauto.key(0, 13)          # Enter
        yield 30
        wins = [r[0] for r in unoauto.probe() if r[1] == 1]
        unoauto.log("open now: %s" % ", ".join(wins))

    def tick(self):
        if self.steps is None:
            return False
        now = unoauto.uptime()
        if now >= self.until:
            try:
                self.until = now + next(self.steps)
            except StopIteration:
                self.steps = None

app = Bot()

unoscript: the permission-gated OS surface

import unoscript is the production automation surface: UI, apps, files, processes, memory, ports and power, each call gated by a capability tier (0 ambient, 1 user, 2 admin, 3 kernel). Denied calls raise OSError; request() asks for a grant (consent sheet, role, or signed manifest) and answers False rather than raising. The model, the manifest story and the full catalog are on Remote control & automation.

import unoscript as u

u.cap_tier("power")                  # -> 2: needs an explicit grant
if u.request("power"):               # consent sheet, role, or manifest
    u.sys.power(0)                   # clean shutdown

u.fs.write("notes/todo.txt", b"buy milk")   # tier 1: USERS/<uid>/notes/...
print(u.fs.read("notes/todo.txt"))          # b'buy milk'  (4 KB read cap)

for pid, tid, state, name, owner in u.proc.list():   # tier 2
    print(pid, name, "focused" if state & 1 else "")

Worked examples: the sample programs. The app model: Python apps. The permission model and unattended grants: Remote control & automation.