NanoApps

Run homebrew apps on iPod nano 7th generation. ▶️ Watch NanoApps in action on YouTube.

NanoApps lets you run a collection of, and build your own, homebrew apps on iPod nano 7th generation. Out of the box it includes essential utilities like Calculator, Countdown Days, Files, Paint, and Screenshots, productivity tools like Calendar, Notes, Reminders, and Books, and lightweight games like 2048, Tetris, Minesweeper, and Rhythm. NanoApps also adds compatibility with AirPods with H2 chip and iPhone Lightning Dock.

Homebrew apps appear as colorful icons on the native nano Home Screen, render with the full LVGL widget toolkit, and launch with the familiar zoom animation, so they feel at home next to Music and Photos. Games and visualization apps can also use OpenGL ES for 3D rendering. Contributions are very welcome: see Contributing to NanoApps, join the NanoApps Discord, and share what you build on r/ipod.

Includes community work from nano7-untethered, andrew867’s NanoApps, NanoBtFix, nano7-a1717-dock, and ipod_sun.

Download and Install NanoApps

1. Download NanoApps-2012-Model.ipsw or NanoApps-2015-Model.ipsw for your iPod nano.
2. Connect the iPod and select it in Finder, iTunes, or Apple Devices. Hold Option on Mac or Shift on Windows while clicking Check for Update, then select the downloaded IPSW.
3. Download NanoApps-disk.zip. Unzip it, and copy all three folders ("Apps", "Data", and "Library") to the top level of the iPod's disk in Finder or File Explorer.
4. Eject the iPod. Homebrew apps will appear automatically on the Home Screen.

To add an app shared by another developer, unzip its app ZIP and copy the .nanoapp folder into the Apps folder on the iPod.

Included Apps

NanoApps ships with a broad collection of apps and games: productivity and reference apps like Notes, Calendar, Wallet, and Elements; creative and utility apps like Paint and Screenshot; arcade, puzzle, card, and board games like 2048, Tetris, Solitaire, and Chess; plus a OpenGL demo app. They group into a few kinds.

Productivity & Reference

• Books: a plain-text book reader with paging and bookmarks.
• Calculator: a touch calculator with decimal support.
• Calendar: day, week, month, and year views with events.
• Contacts: a full contacts list with detail views.
• Countdown Days: count down to birthdays, trips, and deadlines, with yearly repeats.
• Dictionary: English word definitions with T9-driven lookup.
• Elements: an interactive 118-element periodic table.
• Files: browse the iPod filesystem and view text files.
• Notes: a multi-note text editor with an on-screen T9 keyboard.
• Passwords: a credential vault with optional TOTP one-time codes.
• Reminders: a checkable to-do list with quick text entry.
• Wallet: colorful cards for tickets, passes, and loyalty.

Tools & Creativity

• Clock: a modern digital clock face.
• Paint: fast finger painting with a thumbnail library of your drawings.
• Remote: a transport remote for the built-in Music player.
• Screenshot: take and browse screenshots and screen recordings directly on the device.
• Sensors: a toolbox of live hardware readouts (accelerometer, buttons, battery, brightness).
• Spirit Level: a bubble level using the accelerometer.

Games

• 2048: slide tiles to reach 2048.
• Breakout: break the bricks with a paddle and ball.
• Connect 4: drop discs and connect four in a row.
• Crosswords: solve a custom crossword puzzle.
• Golf: top-down mini golf.
• Match 3: a Bejeweled-style match-three puzzle.
• Minesweeper: flag the mines, clear the board.
• Pong: single-player versus an AI paddle.
• Quiz: multiple-choice trivia with built-in and custom decks.
• Rhythm: tap the falling notes in time.
• Simon Says: repeat the growing color sequence from memory.
• Snake: the classic; grow without biting your tail.
• Sudoku: 9x9 with a built-in puzzle bank.
• Tetris: stack falling blocks and clear lines.
• Tic-tac-toe: a 4x4 twist versus an AI.
• Tilt Ball: roll a ball with the accelerometer to collect targets.
• Tower: a Stack-style tap-timing tower builder.
• Wordle: guess the five-letter word in six tries.

Card & Board Games

• Chess: minimalist chess, versus an AI or a second player.
• FreeCell: the open-cell solitaire.
• Heads Up: charades-style guessing with built-in decks.
• Mahjong: single-layer pair-matching.
• Solitaire: Klondike.
• Texas Hold'em: heads-up poker versus an AI.

Graphics & Developer

• Benchmark: LVGL's rendering benchmark on the surface runtime.
• OpenGL: a touch-interactive tour of OpenGL ES 1.1 features, with 3D meshes, textures, and lighting at GPU-backed frame rates.
• Stress: LVGL's stress test.
• Widgets: LVGL's widget gallery demo.

Build and Install NanoApps Yourself

On your Mac or Linux computer, open Terminal, then paste and run these commands:

git clone https://github.com/nfzerox/NanoApps.git
cd NanoApps
./start

The first time you run it, ./start finds the iPod and sets everything up for you, installing anything that is missing. Choose Install all apps from the menu.

Note: the very first build is slow. LVGL has to compile from scratch, which can take a few minutes. This is normal and only happens once; later builds reuse the cached result and are much faster.

The installer restarts the iPod when finished. Homebrew apps will appear automatically on the Home Screen, each as its own colorful icon, with native support for jiggle mode and launch animation.

The menu has everything else too: install a single app, add sample data, and repair the iPod's disk if an install ever hits a read-only error.

Developing Apps

NanoApps gives you a small C SDK (sdk/hb_sdk.h) covering display, multitouch, buttons, accelerometer, battery, brightness, clock, filesystem, audio, and the native UI integration (home screen icons, screen surfaces, screenshots, screen recording). Apps come in three surface kinds: LVGL widgets (software-rendered), OpenGL ES 1.1 (GPU-accelerated 3D), and a direct-framebuffer mode for fast immediate-mode drawing.

How ./start works

./start is the single entry point for everything: building, installing, scaffolding new apps, pulling screenshots, and repairing the disk. It connects directly to the iPod over USB on macOS and Linux. It finds the iPod's disk automatically by its SCSI model, so you never need to know the device node or give the volume a particular name.

On first use it installs anything missing, including the ARM toolchain, Python with Pillow, the Rust toolchain, the pinned LVGL checkout, Font Awesome, the firmware builder, and the USB and filesystem tools.

Build everything without touching the device with ./start build, and run ./start with no arguments for the interactive menu.

Scaffold a new app

./start new clones an existing app of the kind you pick and rewrites its name and identity (folder, source, Makefile, and the Info.plist bundle id, name, and executable) so you get a distinct, buildable app to start from:

./start new my_app                 # LVGL widgets (default), clones Clock
./start new my_game  --kind raw    # direct-framebuffer surface, clones Paint
./start new my_scene --kind gl     # OpenGL ES surface, clones OpenGL
./start new my_app   --from notes  # clone a specific existing app instead

(or pick Create a new app in the ./start menu.) Then edit apps/my_app/my_app.c, build, and install it to the Home Screen:

./start build my_app
./start install my_app             # builds, packs, installs, then tap its icon

How apps are built

Every app is a self-contained, position-independent .hbapp blob plus an Info.plist that carries its identity (bundle id, display name, icon glyph and color). The resident registers apps on the Home Screen and launches them on tap, handing each app a framebuffer surface to render into. App files stay under /Apps, app data under /Data, and runtime files under /Library.

Build a ZIP that anyone can install independently, without adding it to this repository or rebuilding other apps:

./start package my_app             # produces build/packages/my_app.zip

An app's Makefile picks the surface kind:

APP_NAME   := my_app
SRCS       := my_app.c
LV_SURFACE := 1          # LVGL widgets  (or GL_SURFACE := 1, or RAW_SURFACE := 1)
include ../../sdk/hb_app.mk

• LV_SURFACE := 1: draw with the full LVGL v9 widget toolkit. Your entry point is HB_APP_ENTRY(payload_entry); build your UI with LVGL as usual (see apps/clock, apps/notes).
• GL_SURFACE := 1: render 3D with OpenGL ES 1.1. Implement gl_app_init() and gl_app_frame(w, h, frame) (see apps/opengl).
• RAW_SURFACE := 1: draw pixels straight into the framebuffer for fast immediate-mode apps and games. Implement hb_raw_init(w, h) and hb_raw_frame(touch) (see apps/paint).

LVGL widget apps have a budget of roughly 150 to 200 widgets each; dense grids should render to a canvas (see Paint, Elements, and the canvas-based games).

Optional iOS game ports live under ports/. Run python3 tools/build_ios_game.py --help to prepare a matching original IPA and build an app bundle.

Keep the compiled app small. There is a practical ceiling on an app's executable image (code plus bundled assets). If an app grows past roughly half a megabyte, it can fail to launch in a way that's easy to misread as a random bug: the device hangs or reboots when you open the app — and whether it happens can shift between compiler versions, so the same code may run for you and crash for someone else. Large image assets are almost always the cause; a single full-color bitmap can be 50 to 100 KB. If you hit this, downscale big images, use a more compact color format (for example RGB565 instead of ARGB8888 where you don't need alpha), or load them at runtime instead of compiling them in. The build prints the image size when it packs the app, so keep an eye on it and leave some headroom.

Run a one-off harness

apps/ are Home Screen surface apps. For low-level bring-up there are standalone probes under harnesses/ (button, touch, brightness, filesystem, and font tests) that are built and SCSI-exec'd once, without a Home Screen install:

./start run fs_test
./start run button_test

Debugging

Apps can write breadcrumbs to a DRAM trace ring:

hb_trace_reset();
hb_trace_log("BOOT", 0, 0);
hb_trace_log("STEP", 1, 0);

Print the most recent trace entries (the iPod only needs to be attached to your computer):

./start trace

Dump raw DRAM at any address with ./start peek 0x09120000 0x200. After exiting an app you may need to tap the screen once for the normal OS to recover.

If an install fails with Input/output error

If an install prints a run of errors like:

Unmounted /dev/sda1
cp: cannot create regular file '/mnt/nanoapps-ipod/Apps/Executables/Notes.hbapp': Input/output error

the iPod's FAT filesystem is corrupted (usually from an unclean disconnect). Repair it, then install again:

./start fsck

Screenshots & Screen Recordings

Install and open the Screenshot app to capture and browse screenshots and screen recordings right on the device. Set its capture mode, then triple-click the Home button to grab a screenshot or start and stop a recording; everything is saved to the iPod and viewable in the app.

To pull the captured media onto your computer (converted to PNG and GIF, then cleared from the device):

./start pull media

Contributing to NanoApps

Good places to start:

• Build more apps and games. ./start new gets you a working app in seconds.
• Improve the homebrew apps and its LVGL integration.
• Reverse engineer more OS APIs for the homebrew SDK and improve SDK reliability.
• Bring more to the OpenGL ES path: 3D games and visualizations.
• Add Windows development and install support.

Pull requests are welcome. Fork it, play with it, and discuss with fellow hackers on the NanoApps Discord. If you make something cool, post it, share it on r/ipod and social media.