orion128 0.1.0a1__tar.gz

orion128-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan Kosarev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

orion128-0.1.0a1/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: orion128
+Version: 0.1.0a1
+Summary: Orion-128 home computer emulator
+Author-email: Ivan Kosarev <mail@ivankosarev.com>
+License: MIT
+Project-URL: Homepage, https://github.com/kosarev/orion128/
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: X11 Applications
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: System :: Emulators
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: z80>=1.2
+Requires-Dist: pysdl2
+Requires-Dist: numpy
+Dynamic: license-file
+
+# orion128
+
+An emulator of the Orion-128, a home computer built around the KR580VM80A
+processor (an i8080 clone).
+
+[![Python package CI](https://github.com/kosarev/orion128/actions/workflows/python-package.yml/badge.svg)](https://github.com/kosarev/orion128/actions/workflows/python-package.yml)
+[![PyPI](https://img.shields.io/pypi/v/orion128)](https://pypi.org/project/orion128/)
+[![Python](https://img.shields.io/pypi/pyversions/orion128)](https://pypi.org/project/orion128/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/kosarev/orion128/blob/main/LICENSE)
+
+orion128 emulates the hardware — memory-mapped video, the keyboard, ports and
+the disk controller — and runs the real ROM and software on top of it. It is
+built on the [z80](https://github.com/kosarev/z80) package for the i8080 core
+and aims to stay in pure Python. The display is built on PySDL2 and numpy.
+
+It ships with the MS7007 Monitor and an ORDOS 4.03 ROM-disk, so it boots a
+working system out of the box:
+
+```shell
+orion128
+```
+
+`--monitor PATH` and `--romdisk PATH` replace the bundled ROMs. Any further
+arguments are ORDOS files (`.ORD` or `.BRU`) preloaded onto the RAM-disk
+(drive B:):
+
+```shell
+orion128 PENX4$.ORD
+```
+
+<kbd>F12</kbd> is the RESET button. <kbd>F10</kbd> closes the emulator.
+
+The bundled ROMs are the copyright of their original authors and are not
+covered by this package's MIT licence; see `orion128/ROMS.txt`.
+
+This is early work in progress.

orion128-0.1.0a1/README.md

@@ -0,0 +1,36 @@
+# orion128
+
+An emulator of the Orion-128, a home computer built around the KR580VM80A
+processor (an i8080 clone).
+
+[![Python package CI](https://github.com/kosarev/orion128/actions/workflows/python-package.yml/badge.svg)](https://github.com/kosarev/orion128/actions/workflows/python-package.yml)
+[![PyPI](https://img.shields.io/pypi/v/orion128)](https://pypi.org/project/orion128/)
+[![Python](https://img.shields.io/pypi/pyversions/orion128)](https://pypi.org/project/orion128/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/kosarev/orion128/blob/main/LICENSE)
+
+orion128 emulates the hardware — memory-mapped video, the keyboard, ports and
+the disk controller — and runs the real ROM and software on top of it. It is
+built on the [z80](https://github.com/kosarev/z80) package for the i8080 core
+and aims to stay in pure Python. The display is built on PySDL2 and numpy.
+
+It ships with the MS7007 Monitor and an ORDOS 4.03 ROM-disk, so it boots a
+working system out of the box:
+
+```shell
+orion128
+```
+
+`--monitor PATH` and `--romdisk PATH` replace the bundled ROMs. Any further
+arguments are ORDOS files (`.ORD` or `.BRU`) preloaded onto the RAM-disk
+(drive B:):
+
+```shell
+orion128 PENX4$.ORD
+```
+
+<kbd>F12</kbd> is the RESET button. <kbd>F10</kbd> closes the emulator.
+
+The bundled ROMs are the copyright of their original authors and are not
+covered by this package's MIT licence; see `orion128/ROMS.txt`.
+
+This is early work in progress.

orion128-0.1.0a1/orion128/ROMS.txt

@@ -0,0 +1,7 @@
+The bundled ROM images, ms7007.rom and disk.rom, are NOT covered by the
+MIT licence that applies to the rest of orion128.
+
+They contain the Orion-128 Monitor, the ORDOS operating system, the VC
+commander and a character generator. These remain the copyright of their
+original authors and are included only so that the emulator boots a
+working system out of the box.

orion128-0.1.0a1/orion128/__init__.py

@@ -0,0 +1,41 @@
+#   Orion-128 home computer emulator.
+#   https://github.com/kosarev/orion128
+#
+#   Copyright (C) 2026 Ivan Kosarev.
+#   mail@ivankosarev.com
+#
+#   Published under the MIT license.
+
+from ._machine import (
+    CPU_FREQUENCY,
+    IO_BASE,
+    IO_SIZE,
+    KEYBOARD_SCAN,
+    KEYBOARD_SENSE,
+    MONITOR_BASE,
+    MONITOR_SIZE,
+    ROMDISK_PORT,
+    SCREEN_HEIGHT,
+    SCREEN_WIDTH,
+    VIDEO_BASE,
+    VIDEO_SIZE,
+    Orion128Machine,
+)
+from ._main import main
+
+__all__ = [
+    'CPU_FREQUENCY',
+    'IO_BASE',
+    'IO_SIZE',
+    'KEYBOARD_SCAN',
+    'KEYBOARD_SENSE',
+    'MONITOR_BASE',
+    'MONITOR_SIZE',
+    'ROMDISK_PORT',
+    'SCREEN_HEIGHT',
+    'SCREEN_WIDTH',
+    'VIDEO_BASE',
+    'VIDEO_SIZE',
+    'Orion128Machine',
+    'main',
+]

orion128-0.1.0a1/orion128/_display.py

@@ -0,0 +1,137 @@
+#   Orion-128 home computer emulator.
+#   https://github.com/kosarev/orion128
+#
+#   Copyright (C) 2026 Ivan Kosarev.
+#   mail@ivankosarev.com
+#
+#   Published under the MIT license.
+
+import ctypes
+import os
+
+import numpy as np
+import numpy.typing as npt
+import sdl2
+
+from ._machine import SCREEN_HEIGHT, SCREEN_WIDTH
+
+# The MS7007 keyboard: host key to (column, row) matrix crossing. The
+# columns are the port A scan lines, the rows the port B sense lines (0-7)
+# and the top of port C (8-11). The crossings were read off the Monitor
+# itself, by pressing each one and seeing which character it decodes, so
+# the host letter and digit keys reach the Orion keys of the same name.
+_KEY_MATRIX = {
+    sdl2.SDLK_a: (4, 4), sdl2.SDLK_b: (4, 0), sdl2.SDLK_c: (3, 2),
+    sdl2.SDLK_d: (3, 1), sdl2.SDLK_e: (2, 7), sdl2.SDLK_f: (3, 11),
+    sdl2.SDLK_g: (3, 6), sdl2.SDLK_h: (7, 0), sdl2.SDLK_i: (4, 7),
+    sdl2.SDLK_j: (2, 11), sdl2.SDLK_k: (3, 4), sdl2.SDLK_l: (3, 0),
+    sdl2.SDLK_m: (5, 4), sdl2.SDLK_n: (3, 5), sdl2.SDLK_o: (4, 6),
+    sdl2.SDLK_p: (3, 7), sdl2.SDLK_q: (4, 11), sdl2.SDLK_r: (4, 5),
+    sdl2.SDLK_s: (5, 3), sdl2.SDLK_t: (5, 5), sdl2.SDLK_u: (3, 3),
+    sdl2.SDLK_v: (6, 1), sdl2.SDLK_w: (4, 3), sdl2.SDLK_x: (5, 6),
+    sdl2.SDLK_y: (4, 2), sdl2.SDLK_z: (7, 1),
+    sdl2.SDLK_0: (6, 10), sdl2.SDLK_1: (6, 11), sdl2.SDLK_2: (7, 11),
+    sdl2.SDLK_3: (0, 11), sdl2.SDLK_4: (6, 2), sdl2.SDLK_5: (7, 2),
+    sdl2.SDLK_6: (0, 2), sdl2.SDLK_7: (6, 9), sdl2.SDLK_8: (7, 9),
+    sdl2.SDLK_9: (0, 9),
+    sdl2.SDLK_PERIOD: (7, 10), sdl2.SDLK_COMMA: (1, 9),
+    sdl2.SDLK_SEMICOLON: (1, 11), sdl2.SDLK_SLASH: (0, 5),
+    sdl2.SDLK_MINUS: (2, 9), sdl2.SDLK_EQUALS: (0, 6),
+    sdl2.SDLK_QUOTE: (1, 0), sdl2.SDLK_LEFTBRACKET: (2, 0),
+    sdl2.SDLK_RIGHTBRACKET: (2, 1), sdl2.SDLK_BACKSLASH: (6, 0),
+    sdl2.SDLK_SPACE: (0, 0), sdl2.SDLK_RETURN: (0, 10),
+    sdl2.SDLK_LEFT: (5, 0), sdl2.SDLK_RIGHT: (6, 7),
+    sdl2.SDLK_UP: (7, 5), sdl2.SDLK_DOWN: (6, 5),
+    sdl2.SDLK_BACKSPACE: (6, 4), sdl2.SDLK_ESCAPE: (1, 10),
+    # Shift gives the Orion's shifted characters (and lowercase letters).
+    sdl2.SDLK_LSHIFT: (5, 9), sdl2.SDLK_RSHIFT: (5, 9),
+}
+
+# The RESET key is a hardware button, not a matrix key, so it has its own
+# host key.
+_RESET_KEY = sdl2.SDLK_F12
+
+# F10 closes the emulator, as an alternative to closing the window.
+_QUIT_KEY = sdl2.SDLK_F10
+
+
+class Display:
+    '''A window showing the Orion screen, built on SDL.
+
+    It takes the pixel bitmap from the machine and shows it in black and
+    white, scaled up so the small screen is comfortable to look at.
+    '''
+
+    def __init__(self, scale: int = 2, title: str = 'Orion-128') -> None:
+        # On Wayland, use the Wayland driver so the window follows the
+        # system display scaling instead of being upscaled by XWayland.
+        on_wayland = 'WAYLAND_DISPLAY' in os.environ
+        if on_wayland and 'SDL_VIDEODRIVER' not in os.environ:
+            os.environ['SDL_VIDEODRIVER'] = 'wayland'
+
+        sdl2.SDL_Init(sdl2.SDL_INIT_VIDEO)
+
+        # SDL_WINDOW_ALLOW_HIGHDPI makes the drawable the full device-pixel
+        # size on a scaled display, so the window is the intended physical
+        # size and the screen is drawn crisply rather than being upscaled.
+        self.__window = sdl2.SDL_CreateWindow(
+            title.encode(),
+            sdl2.SDL_WINDOWPOS_CENTERED, sdl2.SDL_WINDOWPOS_CENTERED,
+            SCREEN_WIDTH * scale, SCREEN_HEIGHT * scale,
+            sdl2.SDL_WINDOW_SHOWN | sdl2.SDL_WINDOW_ALLOW_HIGHDPI)
+
+        self.__renderer = sdl2.SDL_CreateRenderer(self.__window, -1, 0)
+
+        # A streaming texture the size of the screen; SDL scales it up to
+        # fill the window when it is copied.
+        self.__texture = sdl2.SDL_CreateTexture(
+            self.__renderer, sdl2.SDL_PIXELFORMAT_RGB24,
+            sdl2.SDL_TEXTUREACCESS_STREAMING, SCREEN_WIDTH, SCREEN_HEIGHT)
+
+        self.__quit = False
+        self.__reset_pressed = False
+        self.__keys_down: set[int] = set()
+
+    def update(self, frame: npt.NDArray[np.uint8]) -> None:
+        '''Show the given SCREEN_HEIGHT by SCREEN_WIDTH RGB frame.'''
+        frame = np.ascontiguousarray(frame, dtype=np.uint8)
+        sdl2.SDL_UpdateTexture(
+            self.__texture, None, frame.ctypes.data, SCREEN_WIDTH * 3)
+        sdl2.SDL_RenderClear(self.__renderer)
+        sdl2.SDL_RenderCopy(self.__renderer, self.__texture, None, None)
+        sdl2.SDL_RenderPresent(self.__renderer)
+
+    def closed(self) -> bool:
+        '''Process window events, then report whether close was requested.'''
+        event = sdl2.SDL_Event()
+        while sdl2.SDL_PollEvent(ctypes.byref(event)) != 0:
+            if event.type == sdl2.SDL_QUIT:
+                self.__quit = True
+            elif event.type == sdl2.SDL_KEYDOWN:
+                key = int(event.key.keysym.sym)
+                if key == _QUIT_KEY:
+                    self.__quit = True
+                elif key == _RESET_KEY:
+                    self.__reset_pressed = True
+                else:
+                    self.__keys_down.add(key)
+            elif event.type == sdl2.SDL_KEYUP:
+                self.__keys_down.discard(int(event.key.keysym.sym))
+        return self.__quit
+
+    def pressed_keys(self) -> set[tuple[int, int]]:
+        '''The pressed keys as Orion (column, row) matrix crossings.'''
+        return {_KEY_MATRIX[key]
+                for key in self.__keys_down if key in _KEY_MATRIX}
+
+    def take_reset(self) -> bool:
+        '''Report whether the RESET key was pressed, and clear it.'''
+        pressed = self.__reset_pressed
+        self.__reset_pressed = False
+        return pressed
+
+    def close(self) -> None:
+        sdl2.SDL_DestroyTexture(self.__texture)
+        sdl2.SDL_DestroyRenderer(self.__renderer)
+        sdl2.SDL_DestroyWindow(self.__window)
+        sdl2.SDL_Quit()

orion128-0.1.0a1/orion128/_machine.py

@@ -0,0 +1,307 @@
+#   Orion-128 home computer emulator.
+#   https://github.com/kosarev/orion128
+#
+#   Copyright (C) 2026 Ivan Kosarev.
+#   mail@ivankosarev.com
+#
+#   Published under the MIT license.
+
+import numpy as np
+import numpy.typing as npt
+import z80
+
+# The Orion-128 screen is a bitmap of this size.
+SCREEN_WIDTH = 384
+SCREEN_HEIGHT = 256
+
+# The screen is a bitmap in the processor's address space. Each byte holds
+# eight horizontal pixels, the most significant bit leftmost. The bytes run
+# down a column of the screen before stepping to the next column to the
+# right, so the byte for pixel (x, y) is at
+# VIDEO_BASE + (x // 8) * SCREEN_HEIGHT + y.
+# The base address and this layout are provisional until confirmed against
+# the ROM and the disk images.
+VIDEO_BASE = 0xc000
+VIDEO_SIZE = (SCREEN_WIDTH // 8) * SCREEN_HEIGHT
+
+# The 2K Monitor ROM sits at the top of memory. The i8080 resets to
+# address 0, but on the Orion the reset makes the Monitor run first, and
+# its first byte is a jump into itself. So starting the processor at
+# MONITOR_BASE reproduces the boot without emulating the reset ROM overlay.
+MONITOR_BASE = 0xf800
+MONITOR_SIZE = 0x800
+
+# The processor runs at about 2.5 MHz.
+CPU_FREQUENCY = 2_500_000
+
+# The Orion reaches its hardware through memory, not through i8080 ports.
+# The 8255 chips (keyboard, ROM-disk, user ports) occupy F400-F7FF, and the
+# system latches (colour, RAM page, screen page) share F800-FFFF with the
+# Monitor ROM: reads there return the ROM, writes set the latches.
+IO_BASE = 0xf400
+IO_SIZE = 0x400
+
+# The ROM-disk 8255 lives at F500: F500 reads data, F501 sets the address
+# low byte, F502 the high byte. Writing the address makes the addressed
+# byte appear at the data port for the Monitor to read.
+ROMDISK_PORT = 0xf500
+
+# The keyboard 8255 at F400: port A (F400) drives the scan columns active
+# low, and the sense rows are read active low from port B (F401) for rows
+# 0-7 and the top half of port C (F402) for rows 8-11. A pressed key is a
+# (column, row) crossing that pulls its row low when its column is scanned.
+KEYBOARD_SCAN = 0xf400
+KEYBOARD_SENSE = 0xf401
+KEYBOARD_SENSE_C = 0xf402
+
+# Memory paging. The processor's page for the 0x0000-0xEFFF region is
+# selected through port F9 (or the F900 latch). The selected page is
+# exposed in the core's memory, so reads and writes run at full speed; the
+# other pages are held aside as images. Switching pages saves the exposed
+# page back to its image and copies the newly selected image into the
+# address space. F000-FFFF is common to all pages and never swapped.
+PAGE_SELECT_PORT = 0xf9
+PAGE_SELECT = 0xf900
+PAGED_SIZE = 0xf000
+
+# Pages 1, 2 and 3 are ORDOS's read/write RAM-disks, drives B:, C: and D:.
+# A preloaded RAM-disk goes to page 1, drive B:.
+RAM_DISK_PAGE = 1
+
+# Colour control at F800 (or port F8). Bit D2 turns colour on; without it
+# the screen is monochrome. In 16-colour mode a colour byte at the same
+# address in page 1 holds the background colour in its top nibble and the
+# foreground in its bottom nibble, and the pixel bit chooses between them.
+COLOUR_CONTROL = 0xf800
+COLOUR_CONTROL_PORT = 0xf8
+COLOUR_ON = 0x04
+
+# Monochrome is the Orion's green on black.
+_GREEN = (0x30, 0xff, 0x30)
+
+
+# The 16 colours, one bit each for intensity, red, green and blue.
+def _build_palette() -> npt.NDArray[np.uint8]:
+    palette = np.zeros((16, 3), dtype=np.uint8)
+    for code in range(16):
+        level = 0xff if code & 0x08 else 0xaa
+        palette[code] = (level if code & 0x04 else 0,
+                         level if code & 0x02 else 0,
+                         level if code & 0x01 else 0)
+    return palette
+
+
+_PALETTE = _build_palette()
+
+
+def _to_record(data: bytes) -> bytes:
+    '''Normalise a stored ORDOS file to an on-disk record.
+
+    An on-disk record holds the data length in its size field and no
+    padding. A .ORD file puts the whole file length there (16 more than the
+    data); a .BRU file puts the data length but pads the data to a block
+    boundary. Tell them apart by whether the size field plus the 16-byte
+    header still fits inside the file.
+    '''
+    size = data[10] | (data[11] << 8)
+    data_size = size if 16 + size <= len(data) else len(data) - 16
+    record = bytearray(data[:16 + data_size])
+    record[10:12] = data_size.to_bytes(2, 'little')
+    return bytes(record)
+
+
+class Orion128Machine(z80.I8080Machine):
+    '''The Orion-128 machine: the i8080 core with the Orion's memory.
+
+    The processor reads memory straight from the core, which is fast. Only
+    writes need watching, so a single write handler forms the whole bus: it
+    protects the Monitor ROM, captures the system latches, and leaves the
+    8255 region idle. Banking, the keyboard and the disk controller are
+    still to come.
+    '''
+
+    def __init__(self, monitor: bytes | None = None) -> None:
+        super().__init__()
+        self.__system_ports: dict[int, int] = {}
+        self.__romdisk = b''
+        self.__romdisk_addr = 0
+        self.__scan = 0xff
+        self.__keys: set[tuple[int, int]] = set()
+        self.__page_images = {page: bytearray(PAGED_SIZE) for page in range(4)}
+        self.__current_page = 0
+        self.__colour_control = 0
+        if monitor is not None:
+            self.load_monitor(monitor)
+
+    def load_monitor(self, monitor: bytes) -> None:
+        '''Load the 2K Monitor ROM, set up the bus and start at the entry.'''
+        assert len(monitor) == MONITOR_SIZE
+        self.set_memory_block(MONITOR_BASE, monitor)
+
+        # Idle I/O reads as no key pressed and no ROM-disk present.
+        self.set_memory_block(IO_BASE, b'\xff' * IO_SIZE)
+
+        self.pc = MONITOR_BASE
+
+        # Watch only the I/O and ROM region for writes. Every other write
+        # goes straight to memory in the core, which keeps the processor
+        # fast even while a program repaints the screen.
+        self.set_write_callback(self.__on_write)
+        self.mark_addrs(IO_BASE, 0x10000 - IO_BASE, self.WRITE_MARK)
+
+        # Port F9 selects the memory page.
+        self.set_output_callback(self.__on_output)
+
+    def reset(self) -> None:
+        '''Reset the processor to the Monitor, as the RESET key does.
+
+        RAM, including the RAM-disks, is kept, so the Monitor re-boots ORDOS
+        with everything still in place. The Monitor expects page 0 and a
+        cleared colour mode.
+        '''
+        self.__select_page(0)
+        self.__colour_control = 0
+        self.pc = MONITOR_BASE
+
+    def load_romdisk(self, romdisk: bytes) -> None:
+        '''Attach a ROM-disk image, served through the F500 8255.'''
+        self.__romdisk = romdisk
+        self.__romdisk_addr = 0
+        self.set_memory_block(ROMDISK_PORT, bytes([romdisk[0]]))
+
+    def load_ram_disk(self, files: list[bytes]) -> None:
+        '''Fill the RAM-disk (drive B:, page 1) with ORDOS file records.
+
+        Each ORDOS file is a record: an 8-byte name, a 2-byte load address,
+        a 2-byte size, four more header bytes, then the data. The records
+        lie end to end and an FF byte closes the directory. ORDOS keeps such
+        a preloaded disk instead of clearing it at start-up.
+
+        The files may be in either stored form: a .ORD holds the whole file
+        length in the size field, a .BRU holds the data length and pads the
+        data out to a block boundary. _to_record normalises both.
+        '''
+        image = bytearray(PAGED_SIZE)
+        offset = 0
+        for data in files:
+            record = _to_record(data)
+            # Leave room for the record and the FF terminator after it.
+            if offset + len(record) + 1 > PAGED_SIZE:
+                raise ValueError(
+                    f'the RAM-disk (drive B:) holds {PAGED_SIZE} bytes; '
+                    f'these files do not fit')
+            image[offset:offset + len(record)] = record
+            offset += len(record)
+        image[offset] = 0xff
+        self.__page_images[RAM_DISK_PAGE][:] = image
+
+    def set_keys(self, keys: set[tuple[int, int]]) -> None:
+        '''Set the pressed keys as (column, row) matrix crossings.'''
+        self.__keys = set(keys)
+        self.__update_keyboard()
+
+    def __update_keyboard(self) -> None:
+        # A pressed key pulls its sense row low while its scan column is
+        # driven low. Rows 0-7 report on port B, rows 8-11 on the top of
+        # port C.
+        sense_b = 0xff
+        sense_c = 0xff
+        for column, row in self.__keys:
+            if not (self.__scan >> column) & 1:
+                if row < 8:
+                    sense_b &= ~(1 << row) & 0xff
+                else:
+                    sense_c &= ~(1 << (row - 8 + 4)) & 0xff
+        self.set_memory_block(KEYBOARD_SENSE, bytes([sense_b]))
+        self.set_memory_block(KEYBOARD_SENSE_C, bytes([sense_c]))
+
+    def __on_write(self, addr: int, value: int) -> None:
+        # Only F400-FFFF is marked for this handler; the paged region below
+        # writes straight to the core's memory.
+        # The Monitor ROM and the system latches sit at MONITOR_BASE and
+        # above. Capture the latch writes and never touch the ROM. The F900
+        # latch also selects the memory page.
+        if addr >= MONITOR_BASE:
+            self.__system_ports[addr] = value
+            if addr == PAGE_SELECT:
+                self.__select_page(value)
+            elif addr == COLOUR_CONTROL:
+                self.__colour_control = value
+            return
+
+        # The 8255 region. Writing the ROM-disk address ports makes the
+        # addressed byte appear at its data port. Writing the keyboard scan
+        # column updates the sense rows for the pressed keys.
+        if self.__romdisk and ROMDISK_PORT < addr <= ROMDISK_PORT + 2:
+            self.__set_romdisk_address(addr, value)
+        elif addr == KEYBOARD_SCAN:
+            self.__scan = value
+            self.__update_keyboard()
+
+    def __on_output(self, port: int, value: int) -> None:
+        if port & 0xff == PAGE_SELECT_PORT:
+            self.__select_page(value)
+        elif port & 0xff == COLOUR_CONTROL_PORT:
+            self.__colour_control = value
+
+    def __select_page(self, page: int) -> None:
+        page &= 0x03
+        if page == self.__current_page:
+            return
+
+        # Save the exposed page back to its image, then expose the newly
+        # selected page. The core's memory always holds the current page,
+        # so ordinary reads and writes stay at full speed.
+        self.__page_images[self.__current_page][:] = self.memory[:PAGED_SIZE]
+        self.set_memory_block(0, self.__page_images[page])
+        self.__current_page = page
+
+    def __set_romdisk_address(self, addr: int, value: int) -> None:
+        if addr == ROMDISK_PORT + 1:
+            self.__romdisk_addr = (self.__romdisk_addr & 0xff00) | value
+        else:
+            self.__romdisk_addr = (self.__romdisk_addr & 0x00ff) | (value << 8)
+        byte = self.__romdisk[self.__romdisk_addr % len(self.__romdisk)]
+        self.set_memory_block(ROMDISK_PORT, bytes([byte]))
+
+    def __page_memory(self, page: int) -> bytes | bytearray | memoryview:
+        if page == self.__current_page:
+            return self.memory
+        return self.__page_images[page]
+
+    def read_screen(self) -> npt.NDArray[np.uint8]:
+        '''Return the screen as a SCREEN_HEIGHT by SCREEN_WIDTH array of
+        pixels, each 0 or 1.'''
+        video = np.frombuffer(
+            self.__page_memory(0), dtype=np.uint8, count=VIDEO_SIZE,
+            offset=VIDEO_BASE)
+
+        # Bytes go down a column, so the buffer is columns of pixels; put
+        # the rows first, then expand each byte into its eight pixels.
+        columns = video.reshape(SCREEN_WIDTH // 8, SCREEN_HEIGHT)
+        return np.unpackbits(columns.T, axis=1)
+
+    def render(self) -> npt.NDArray[np.uint8]:
+        '''Return the screen as a SCREEN_HEIGHT by SCREEN_WIDTH RGB frame,
+        in the current colour mode.'''
+        pixels = self.read_screen()
+
+        # Monochrome until a program turns colour on.
+        if not self.__colour_control & COLOUR_ON:
+            frame = np.zeros((SCREEN_HEIGHT, SCREEN_WIDTH, 3), dtype=np.uint8)
+            frame[pixels != 0] = _GREEN
+            return frame
+
+        # 16-colour: the colour byte for each pixel byte is at the same
+        # address in page 1. Its top nibble is the background colour and its
+        # bottom nibble the foreground; the pixel bit chooses between them.
+        colour = np.frombuffer(
+            self.__page_memory(1), dtype=np.uint8, count=VIDEO_SIZE,
+            offset=VIDEO_BASE)
+        per_byte = colour.reshape(SCREEN_WIDTH // 8, SCREEN_HEIGHT).T
+        per_pixel = np.repeat(per_byte, 8, axis=1)
+        foreground = per_pixel & 0x0f
+        background = per_pixel >> 4
+        index = np.where(pixels != 0, foreground, background)
+        coloured: npt.NDArray[np.uint8] = _PALETTE[index]
+        return coloured

orion128-0.1.0a1/orion128/_main.py

@@ -0,0 +1,76 @@
+#   Orion-128 home computer emulator.
+#   https://github.com/kosarev/orion128
+#
+#   Copyright (C) 2026 Ivan Kosarev.
+#   mail@ivankosarev.com
+#
+#   Published under the MIT license.
+
+import sys
+import time
+from pathlib import Path
+
+from ._display import Display
+from ._machine import CPU_FREQUENCY, Orion128Machine
+
+# The window is redrawn this many times a second, and the processor runs a
+# matching slice of ticks between redraws, so it runs at about real speed.
+FRAMES_PER_SECOND = 50
+
+# The bundled default ROMs live next to this module.
+_PACKAGE = Path(__file__).parent
+
+
+def _take_path(args: list[str], option: str) -> str:
+    if not args:
+        sys.exit(f'orion128: {option} needs a path')
+    return args.pop(0)
+
+
+def _parse_args(args: list[str]) -> tuple[Path, Path, list[Path]]:
+    '''Read the leading options -- '--monitor PATH' and '--romdisk PATH',
+    each defaulting to the bundled ROM -- followed by any number of ORDOS
+    files (.ORD or .BRU) to preload onto the RAM-disk (drive B:).'''
+    monitor = _PACKAGE / 'ms7007.rom'
+    romdisk = _PACKAGE / 'disk.rom'
+    while args and args[0].startswith('--'):
+        option = args.pop(0)
+        if option == '--monitor':
+            monitor = Path(_take_path(args, option))
+        elif option == '--romdisk':
+            romdisk = Path(_take_path(args, option))
+        else:
+            sys.exit(f'orion128: unknown option: {option}')
+    files = [Path(arg) for arg in args]
+    return monitor, romdisk, files
+
+
+def main() -> None:
+    '''The orion128 command-line entry point.
+
+    It runs the machine and shows its screen until the window is closed. By
+    default it boots the bundled Monitor and ORDOS ROM-disk; '--monitor
+    PATH' and '--romdisk PATH' replace them. Any further arguments are ORDOS
+    files (.ORD or .BRU) preloaded onto the RAM-disk (drive B:).
+    '''
+    monitor, romdisk, files = _parse_args(sys.argv[1:])
+
+    machine = Orion128Machine()
+    machine.load_monitor(monitor.read_bytes())
+    machine.load_romdisk(romdisk.read_bytes())
+    if files:
+        machine.load_ram_disk([path.read_bytes() for path in files])
+
+    ticks_per_frame = CPU_FREQUENCY // FRAMES_PER_SECOND
+    display = Display()
+    try:
+        while not display.closed():
+            if display.take_reset():
+                machine.reset()
+            machine.set_keys(display.pressed_keys())
+            machine.ticks_to_stop = ticks_per_frame
+            machine.run()
+            display.update(machine.render())
+            time.sleep(1 / FRAMES_PER_SECOND)
+    finally:
+        display.close()

orion128-0.1.0a1/orion128.egg-info/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: orion128
+Version: 0.1.0a1
+Summary: Orion-128 home computer emulator
+Author-email: Ivan Kosarev <mail@ivankosarev.com>
+License: MIT
+Project-URL: Homepage, https://github.com/kosarev/orion128/
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: X11 Applications
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: System :: Emulators
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: z80>=1.2
+Requires-Dist: pysdl2
+Requires-Dist: numpy
+Dynamic: license-file
+
+# orion128
+
+An emulator of the Orion-128, a home computer built around the KR580VM80A
+processor (an i8080 clone).
+
+[![Python package CI](https://github.com/kosarev/orion128/actions/workflows/python-package.yml/badge.svg)](https://github.com/kosarev/orion128/actions/workflows/python-package.yml)
+[![PyPI](https://img.shields.io/pypi/v/orion128)](https://pypi.org/project/orion128/)
+[![Python](https://img.shields.io/pypi/pyversions/orion128)](https://pypi.org/project/orion128/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/kosarev/orion128/blob/main/LICENSE)
+
+orion128 emulates the hardware — memory-mapped video, the keyboard, ports and
+the disk controller — and runs the real ROM and software on top of it. It is
+built on the [z80](https://github.com/kosarev/z80) package for the i8080 core
+and aims to stay in pure Python. The display is built on PySDL2 and numpy.
+
+It ships with the MS7007 Monitor and an ORDOS 4.03 ROM-disk, so it boots a
+working system out of the box:
+
+```shell
+orion128
+```
+
+`--monitor PATH` and `--romdisk PATH` replace the bundled ROMs. Any further
+arguments are ORDOS files (`.ORD` or `.BRU`) preloaded onto the RAM-disk
+(drive B:):
+
+```shell
+orion128 PENX4$.ORD
+```
+
+<kbd>F12</kbd> is the RESET button. <kbd>F10</kbd> closes the emulator.
+
+The bundled ROMs are the copyright of their original authors and are not
+covered by this package's MIT licence; see `orion128/ROMS.txt`.
+
+This is early work in progress.

orion128-0.1.0a1/orion128.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+LICENSE
+README.md
+pyproject.toml
+orion128/ROMS.txt
+orion128/__init__.py
+orion128/_display.py
+orion128/_machine.py
+orion128/_main.py
+orion128/disk.rom
+orion128/ms7007.rom
+orion128/py.typed
+orion128.egg-info/PKG-INFO
+orion128.egg-info/SOURCES.txt
+orion128.egg-info/dependency_links.txt
+orion128.egg-info/entry_points.txt
+orion128.egg-info/requires.txt
+orion128.egg-info/top_level.txt
+tests/test_import.py
+tests/test_machine.py

orion128-0.1.0a1/orion128.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

orion128-0.1.0a1/orion128.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+orion128 = orion128:main

orion128-0.1.0a1/orion128.egg-info/requires.txt

@@ -0,0 +1,3 @@
+z80>=1.2
+pysdl2
+numpy

orion128-0.1.0a1/orion128.egg-info/top_level.txt

@@ -0,0 +1 @@
+orion128

orion128-0.1.0a1/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ['setuptools>=61.0', 'wheel']
+build-backend = 'setuptools.build_meta'
+
+[project]
+name = 'orion128'
+version = '0.1.0a1'
+description = 'Orion-128 home computer emulator'
+readme = 'README.md'
+license = {text = 'MIT'}
+authors = [
+  {name = 'Ivan Kosarev', email = 'mail@ivankosarev.com'}
+]
+requires-python = '>=3.10'
+dependencies = [
+  'z80>=1.2',
+  'pysdl2',
+  'numpy',
+]
+classifiers = [
+  'Development Status :: 3 - Alpha',
+  'Environment :: X11 Applications',
+  'Intended Audience :: Developers',
+  'Intended Audience :: End Users/Desktop',
+  'Operating System :: OS Independent',
+  'Programming Language :: Python :: 3',
+  'Programming Language :: Python :: 3.10',
+  'Programming Language :: Python :: 3.11',
+  'Programming Language :: Python :: 3.12',
+  'Programming Language :: Python :: 3.13',
+  'Programming Language :: Python :: Implementation :: CPython',
+  'Topic :: Games/Entertainment',
+  'Topic :: System :: Emulators',
+  'Typing :: Typed',
+]
+
+[project.urls]
+Homepage = 'https://github.com/kosarev/orion128/'
+
+[project.scripts]
+orion128 = 'orion128:main'
+
+[tool.setuptools]
+packages = ['orion128']
+
+[tool.setuptools.package-data]
+# py.typed is the PEP 561 marker telling type checkers the package
+# carries type information. The .rom files are the bundled default Monitor
+# and ORDOS ROM-disk; ROMS.txt is their copyright notice.
+orion128 = ['py.typed', '*.rom', 'ROMS.txt']
+
+[tool.ruff]
+# Anchors the ruff project root, so the orion128 package is recognised as
+# first-party regardless of the directory ruff is invoked from.
+
+# Match pycodestyle, so ruff does not keep imports on lines it rejects.
+line-length = 79
+
+[tool.ruff.lint]
+# Reject needlessly quoted type annotations.
+extend-select = ['UP037']

orion128-0.1.0a1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

orion128-0.1.0a1/tests/test_import.py

@@ -0,0 +1,12 @@
+#   Orion-128 home computer emulator.
+#   https://github.com/kosarev/orion128
+#
+#   Copyright (C) 2026 Ivan Kosarev.
+#   mail@ivankosarev.com
+#
+#   Published under the MIT license.
+
+
+def test_import() -> None:
+    import orion128
+    assert orion128 is not None

orion128-0.1.0a1/tests/test_machine.py

@@ -0,0 +1,202 @@
+#   Orion-128 home computer emulator.
+#   https://github.com/kosarev/orion128
+#
+#   Copyright (C) 2026 Ivan Kosarev.
+#   mail@ivankosarev.com
+#
+#   Published under the MIT license.
+
+import orion128
+
+
+def test_load_monitor() -> None:
+    # A synthetic ROM whose first byte is the reset jump, as the real
+    # Monitor's is.
+    monitor = bytes([0xc3, 0x42, 0xf8]) + bytes(orion128.MONITOR_SIZE - 3)
+    machine = orion128.Orion128Machine(monitor)
+    assert machine.pc == orion128.MONITOR_BASE
+    start = orion128.MONITOR_BASE
+    assert bytes(machine.memory[start:start + 3]) == bytes([0xc3, 0x42, 0xf8])
+
+
+def test_io_bus() -> None:
+    # A monitor that stores to a system latch (F800) and to RAM (0x1234),
+    # then halts.
+    code = bytes([
+        0x3e, 0x99,        # MVI A, 0x99
+        0x32, 0x00, 0xf8,  # STA 0xF800   -- a latch; the ROM must survive
+        0x32, 0x34, 0x12,  # STA 0x1234   -- ordinary RAM
+        0x76,              # HLT
+    ])
+    monitor = code + bytes(orion128.MONITOR_SIZE - len(code))
+    machine = orion128.Orion128Machine(monitor)
+    machine.ticks_to_stop = 1000
+    machine.run()
+
+    # The write to F800 was captured as a latch, not stored, so the ROM
+    # byte there is unchanged.
+    assert machine.memory[0xf800] == monitor[0]
+    # The write to RAM went through.
+    assert machine.memory[0x1234] == 0x99
+
+
+def test_paging() -> None:
+    # Write a byte to page 1, read it back to common memory, return to
+    # page 0, and halt.
+    code = bytes([
+        0x3e, 0x01, 0xd3, 0xf9,  # MVI A,1; OUT F9    -- select page 1
+        0x3e, 0x5a,              # MVI A, 0x5A
+        0x32, 0x00, 0x20,        # STA 0x2000         -- into page 1
+        0x3a, 0x00, 0x20,        # LDA 0x2000         -- back from page 1
+        0x32, 0x00, 0xf0,        # STA 0xF000         -- common memory
+        0xaf, 0xd3, 0xf9,        # XRA A; OUT F9      -- select page 0
+        0x76,                    # HLT
+    ])
+    monitor = code + bytes(orion128.MONITOR_SIZE - len(code))
+    machine = orion128.Orion128Machine(monitor)
+    machine.ticks_to_stop = 1000
+    machine.run()
+
+    # Page 0 at 0x2000 is untouched; the byte went to page 1 and read back.
+    assert machine.memory[0x2000] == 0x00
+    assert machine.memory[0xf000] == 0x5a
+
+
+def test_romdisk() -> None:
+    # A monitor that sets the ROM-disk address to 0x1234, reads the data
+    # port, stores the byte to RAM, then halts.
+    code = bytes([
+        0x3e, 0x34,        # MVI A, 0x34
+        0x32, 0x01, 0xf5,  # STA 0xF501   -- address low
+        0x3e, 0x12,        # MVI A, 0x12
+        0x32, 0x02, 0xf5,  # STA 0xF502   -- address high
+        0x3a, 0x00, 0xf5,  # LDA 0xF500   -- the data port
+        0x32, 0x00, 0x10,  # STA 0x1000
+        0x76,              # HLT
+    ])
+    monitor = code + bytes(orion128.MONITOR_SIZE - len(code))
+    machine = orion128.Orion128Machine(monitor)
+
+    romdisk = bytearray(0x10000)
+    romdisk[0x1234] = 0x5a
+    machine.load_romdisk(bytes(romdisk))
+
+    machine.ticks_to_stop = 1000
+    machine.run()
+    assert machine.memory[0x1000] == 0x5a
+
+
+def test_keyboard() -> None:
+    # A monitor that drives scan column 2 low, reads the sense rows, stores
+    # them to RAM, then halts.
+    code = bytes([
+        0x3e, 0xfb,        # MVI A, 0xFB   -- column 2 low
+        0x32, 0x00, 0xf4,  # STA 0xF400    -- scan
+        0x3a, 0x01, 0xf4,  # LDA 0xF401    -- sense
+        0x32, 0x00, 0x10,  # STA 0x1000
+        0x76,              # HLT
+    ])
+    monitor = code + bytes(orion128.MONITOR_SIZE - len(code))
+    machine = orion128.Orion128Machine(monitor)
+
+    # A key at column 2, row 3, plus one on another column that must stay
+    # invisible while column 2 is scanned.
+    machine.set_keys({(2, 3), (5, 6)})
+    machine.ticks_to_stop = 1000
+    machine.run()
+
+    # Row 3 pulled low, the rest high: 0xFF & ~(1 << 3) == 0xF7.
+    assert machine.memory[0x1000] == 0xf7
+
+
+def test_ordos_record_formats() -> None:
+    from orion128._machine import _to_record
+    header = b'FILE    ' + (0x100).to_bytes(2, 'little')
+
+    # A .ORD file: the size field is the whole file length.
+    ord_file = header + (24).to_bytes(2, 'little') + bytes(4) + b'12345678'
+    record = _to_record(ord_file)
+    assert len(record) == 24
+    assert (record[10] | (record[11] << 8)) == 8
+    assert record[16:] == b'12345678'
+
+    # A .BRU file: the size field is the data length, with block padding.
+    bru_file = (header + (8).to_bytes(2, 'little') + bytes(4)
+                + b'12345678' + bytes(40))
+    record = _to_record(bru_file)
+    assert len(record) == 24
+    assert (record[10] | (record[11] << 8)) == 8
+    assert record[16:] == b'12345678'
+
+
+def test_reset() -> None:
+    machine = orion128.Orion128Machine()
+    machine.set_memory_block(0x1000, bytes([0x5a]))
+    machine.reset()
+    # The processor is back at the Monitor, and RAM is kept.
+    assert machine.pc == orion128.MONITOR_BASE
+    assert machine.memory[0x1000] == 0x5a
+
+
+def test_ram_disk() -> None:
+    # Preload a record, then read the RAM-disk page's first byte back to
+    # common memory.
+    code = bytes([
+        0x3e, 0x01, 0xd3, 0xf9,  # select page 1 (the RAM-disk)
+        0x3a, 0x00, 0x00,        # LDA 0x0000
+        0x32, 0x00, 0xf0,        # STA 0xF000  (common memory)
+        0xaf, 0xd3, 0xf9,        # select page 0
+        0x76,                    # HLT
+    ])
+    monitor = code + bytes(orion128.MONITOR_SIZE - len(code))
+    machine = orion128.Orion128Machine(monitor)
+
+    record = b'HELLO   ' + bytes([0x00, 0x10, 0x08, 0x00, 0, 0, 0, 0])
+    machine.load_ram_disk([record])
+    machine.ticks_to_stop = 1000
+    machine.run()
+    assert machine.memory[0xf000] == ord('H')
+
+
+def test_render_monochrome() -> None:
+    machine = orion128.Orion128Machine()
+    machine.set_memory_block(orion128.VIDEO_BASE, bytes([0x80]))
+    frame = machine.render()
+    assert frame.shape == (orion128.SCREEN_HEIGHT, orion128.SCREEN_WIDTH, 3)
+    # The lit top-left pixel is drawn, the next one is dark.
+    assert frame[0, 0].any()
+    assert not frame[0, 1].any()
+
+
+def test_screen_pixel_layout() -> None:
+    machine = orion128.Orion128Machine()
+    screen = machine.read_screen()
+    assert screen.shape == (orion128.SCREEN_HEIGHT, orion128.SCREEN_WIDTH)
+    assert not screen.any()
+
+    # The first video byte is the leftmost eight pixels of the top row,
+    # the most significant bit first.
+    machine.set_memory_block(orion128.VIDEO_BASE, bytes([0x80]))
+    screen = machine.read_screen()
+    assert screen[0, 0] == 1
+    assert screen[0, 1] == 0
+
+    # The least significant bit of that byte is its rightmost pixel.
+    machine.set_memory_block(orion128.VIDEO_BASE, bytes([0x01]))
+    screen = machine.read_screen()
+    assert screen[0, 7] == 1
+    assert screen[0, 6] == 0
+
+    # Stepping the address by the screen height moves right by one byte.
+    machine.set_memory_block(orion128.VIDEO_BASE, bytes([0x00]))
+    machine.set_memory_block(
+        orion128.VIDEO_BASE + orion128.SCREEN_HEIGHT, bytes([0x80]))
+    screen = machine.read_screen()
+    assert screen[0, 8] == 1
+
+    # Stepping the address by one moves down by one row.
+    machine.set_memory_block(
+        orion128.VIDEO_BASE + orion128.SCREEN_HEIGHT, bytes([0x00]))
+    machine.set_memory_block(orion128.VIDEO_BASE + 1, bytes([0x80]))
+    screen = machine.read_screen()
+    assert screen[1, 0] == 1