Installable binary files to the AlphaSmart device have an extension ".os3kapp". Several of these come with the official AlphaSmart NEO Manager software - the tool used to link a NEO to PC and perform software updates, copy files, manage classroom activities, etc.

What makes an os3kapp tick? Lucky me, someone has already worked out most of the wrapper format as part of an open, OSX version of the NEO File Manager - take a look at tSoniq's "AlphaSync" code here: https://github.com/tSoniq/alphasync This is the same person who figured out the font code and produced a font editor.

Here's a spec. This being the Motorola 68000, all values are BIG ENDIAN.

• Header - 0x94 bytes
  • uint32: File Signature (must be 0xc0ffeead)
  • uint32: ROM Usage (must match file size)
  • uint32: RAM Usage
  • uint32: Settings Offset (0 if app lacks settings)
  • uint32: Flags. Mostly unknown for now - the lowest byte seems to make a difference, of which the lowest bit means "applet is hidden from applets menu" (for system apps)
  • uint16: Unique App ID. Files with duplicate IDs cannot be installed on a device.
  • uint8: Header Version (usually 1)
  • uint8: File Count (?)
  • 36x char: App Name, null-terminated
  • uint8: File Version (Major)
  • uint8: File Version (Minor)
  • char: File Revision (alphabetic)
  • uint8: Language ID, index into this table:
    • "English (US)",
      "English (UK)",
      "French",
      "French (CR)",
      "Italian",
      "German",
      "Spanish",
      "Dutch",
      "Swedish",
      "<unknown>"
  • 60x char: File Information (null-terminated)
  • uint32: Minimum ASM Version required (?)
  • uint32: File Space Needed (in SRAM - adding this to RAM Usage above gives a "total RAM requirement")
  • uint32: Code Entry Point (I guess)
  • uint32: unknown0 (always 0)
  • uint32: unknown1 (always 1)
  • uint32: unknown2 (always 2)
• 68000 Code - variable length
  • If settings offset is 0, this is every byte from 0x94 up to 4 from the end of the file.
  • Otherwise, it's every byte from 0x94 up to settings_offset - 1
• Settings - variable length - only present if settings offset is nonzero
  • Beginning from this point read structures:
    • uint16: Settings Type: use these types to decode the Value
      • 0x0000: end of Settings List marker
      • 0x0001: null-terminated Label
      • 0x0102: uint32 in range: {default, min, max}
      • 0x0103: list of uint16 IDs: {default, a, b, c, ...}
      • 0x0105: null-terminated password, max 6 letters
      • 0x0106: null-terminated string constant (for description)
      • 0xc001: null-terminated file password (use ident to know WHICH file)
      • 0x8002: uint16 Applet ID
    • uint16: Settings Ident
      • Bit 31 is set if this ident is app-specific or clear if it is global
      • Bit 30 is set for passwords
      • Some IDs
        • 0x0000: none (end of list marker)
        • 0x1001: "On"
        • 0x1002: "Off"
        • 0x100C: "Yes"
        • 0x100D: "No"
        • 0x400b: master password, see type 0x0105
        • 0x8003: Clear All AlphaWord Files (see type 0x0103)
        • 0x1010: Maximum AlphaWord File Size
        • 0x1011: Minimum AlphaWord File Size
    • uint16: Settings Length
    • Length x char: Settings Value
    • Skip one byte if Length was odd (68k memory access is 2byte aligned)
  • Stop after reading Type = 0
  • There may be unused bytes between this point and Footer, but are usually all 0.
• Footer
  • uint32: always 0xcafefeed

Settings are a weird bunch that deserve extra mention. They control SmartApplets behavior on the device, but are also parsed by the GUI in NeoManager and used to build a special Settings panel. This allows control of the settings from the PC before copying an installation to a bunch of NEO in the field.

Using this info, I was able to knock together a decoder in Perl (project Files section) that prints information about a SmartApplet. It also dumps the 68k binary content into a .bin file, which I can load to a disassembler to see how it ticks. Here is Beamer.os3kapp, the IR communications tool.

grkenn@server:~/src/AlphaSmart % ./smartapp-tool.pl SmartApplets/Beamer.OS3KApp
SmartApplets/Beamer.OS3KApp
        magic = 0xc0ffeead      [VALID]
        rom_file_size = 32580   [VALID]
        ram_file_size = 2076
        settings_offset = 32392
        flags = 0xff000000
        id = 0xa006
        header_version = 1
        file_count = 0
        name = 'Beamer'
        Version = 1.01
        language_id = English (UK)
        info = 'Copyright (c) 2005-2012 by Renaissance Learning, Inc.'
        min_asm_version = 0
        file_space = 0
        entry_offset = 148
        unknown0 = 0
        unknown1 = 1
        unknown2 = 2

SETTINGS
        t: 1, i: 32768, l: 12
                Permit Send
        t: 1, i: 32769, l: 30
                Warn if overwriting clipboard
        t: 1, i: 32770, l: 38
                Send to Palm device as ALPHAWORD file
        t: 1, i: 32771, l: 24
                Require master password
        t: 259, i: 32768, l: 6
                On: On,Off
        t: 259, i: 32769, l: 6
                On: On,Off
        t: 259, i: 32770, l: 6
                On: On,Off
        t: 259, i: 32771, l: 6
                Off: On,Off
        t: 0, i: 0, l: 0
                [END]

        footer = 0xcafefeed     [VALID]

You can see that the various type 259 here have the same ident as the type 1s: in other words, the Label describes the Option. Here's the same app from within NEO Manager.

And the Settings Panel it creates - complete with Windows 7 UI errors : )

---

Something I think would be very valuable is to get a ROM dump of the machine. Probably this would entail generating my own SmartApplet that reads ROM data, copies it to SRAM, and then uploads that to PC in parts. By combining this all together, I can get a ROM image that I can then build an emulator around.