neo-play 0.2.1

NEOPlay — chợ ứng dụng & launcher cho thiết bị NEO (ARM Linux)

NEOPlay

Tiếng Việt · English

App store & launcher for NEO devices (ARM Linux) — by ThingEdu.

Like Google Play, but built for NEO. One-tap install, offline-first, curated, safe for kids.

Table of Contents

• Description
• Features
• Installation
• Documentation
• Contributing

Description

NEOPlay is the app store and launcher for the NEO family of ARM Linux devices (NEO One, NEO AI). The goal: a student opens NEOPlay → sees an app in the "New" shelf → taps Install → taps Open. Done, in exactly two taps.

Built with PyQt6, it runs on 2GB-RAM machines, works offline-first (installed apps need no network), and ships a catalog curated by hand at ThingEdu so content stays safe for kids.

Features

• One-tap install — a single state button: Install → Installing → Open.
• Offline-first — the catalog is cached locally; installed apps still open with no network.
• ThingEdu-curated catalog — pinned version, scripts pointed at git tags, sha256 verified before running (never a raw curl | bash).
• Multiple install backends — script-source (NEO App Script Convention v0) as the primary path, plus Flathub for FOSS apps.
• Launchpad-style UI — large rounded app icons, a light blue theme, friendly for kids.
• Classroom mode — fullscreen autostart + kiosk allowlist, so kids only see approved apps.

Installation

On a NEO device

Installs from PyPI; Qt/PyQt6 comes from the apt packages already on the image (no source build):

# normal install (icon in the menu)
curl -sSL https://raw.githubusercontent.com/ThingEdu/neo-play-catalog/main/scripts/install_on_neo.sh | bash

# boot straight into NEOPlay fullscreen
curl -sSL https://raw.githubusercontent.com/ThingEdu/neo-play-catalog/main/scripts/install_on_neo.sh | bash -s -- --autostart

Uninstall: append -s -- --uninstall to the command above.

Classroom mode (recommended)

Install with --autostart and enable kiosk in ~/.config/neoplay/config.toml on the device:

fullscreen = true

[kiosk]
enabled = true
allowlist = ["neo-code", "gcompris"]

The machine boots straight into NEOPlay fullscreen, kids only see approved apps, and the Esc key is disabled (with kiosk off, Esc exits fullscreen normally). Quick test on a dev machine: NEOPLAY_FULLSCREEN=1 make run.

Run on a dev machine

make venv
make run

Pulls the live catalog from the neo-play-catalog repo. Needs network + a display (X11/Wayland).

Documentation

• MVP spec: docs/superpowers/specs/2026-06-06-neoplay-mvp-design.md
• UI Launchpad spec: docs/superpowers/specs/2026-06-06-neoplay-ui-launchpad-design.md
• Boot/Fullscreen spec: docs/superpowers/specs/2026-06-06-neoplay-boot-fullscreen-design.md
• Plan: docs/superpowers/plans/2026-06-06-neoplay-mvp.md

Contributing

Add an app to the shelf (ThingEdu review process)

1. The app has an install script meeting NEO App Script Convention v0 (see the spec in docs/).
2. Pin the script: python tools/pin_script.py <url-pointing-at-tag-vX.Y.Z> → copy the entry into catalog/catalog.json.
3. make check → open a PR → CI validates → on merge the app appears on every device.

Development

make venv          # create .venv + install dev deps
make test          # full unit + UI smoke suite
make check         # validate catalog.json

Code contributions: branch off main, write tests first (TDD), get make test green, and open a PR that clearly describes the change.

Packaging & release

make build         # build sdist + wheel
make dist          # clean + build + twine check
make publish       # scripts/publish.sh (TestPyPI → confirm → PyPI)