• SmartApplet format

    Greg Kennedy • 07/04/2017 at 03:24 • 5 comments

    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...
    Read more »

  • What's inside?

    Greg Kennedy • 07/01/2017 at 01:43 • 1 comment

    I was going to open up my NEO unit to see what's inside. But, fortunately, people have already done that. There is a CR2032 coin-cell inside that serves as backup to retain SRAM while the AA batteries are removed. Some power users have opened their units to replace the lithium backup battery, and photographed the innards.

    https://www.flickr.com/photos/83235901@N00/5347018436/

    https://www.flickr.com/photos/83235901@N00/5346409483/

    http://imgur.com/gx9aJdX

    So, what have we here? Well, there's...

    Based on how the device functions: the system appears to store the OS and applications on the flash chip, do all computation using the processor within the SoC and attached SRAM temp area, and store the users' writing on the SRAM too. This makes a lot of sense, because the device is from the Early Days of flashmem, and it would be smart to limit the number of writes to the chip - like, don't save every time a key is pressed. Also, if the batteries run out, the OS and apps won't disappear : )

    Disappointingly, it doesn't appear possible to give space to the text editor at the expense of apps. They live in separate RAM environments. Scratch that long-requested feature off the list.

    The USB opens up possibility to read and write to an external drive...

    When you install the NEO Manager software, it unpacks a number of files of format ".os3kapp". These are the SmartApplets that you can install to the device. Now that we know the CPU architecture, and we have local dumps of the applications, maybe it's time to dig up a 68000 disassembler.

  • Background

    Greg Kennedy • 06/30/2017 at 22:47 • 0 comments

    A recent comment on the Hackaday blog (https://hackaday.com/2017/06/24/a-goldmine-of-radio-shack-goodies-is-up-for-auction/#comment-3700073) turned me on to this sweet piece of hardware. I decided I should snap one up, certainly before NaNoWriMo season kicks into high gear and the price shoots up again.

    It arrived today. There is great potential here, and largely untapped too - the sum total of knowledge about this device now lives on in this Flickr group: https://www.flickr.com/groups/alphasmart/discuss/

    This device connects to a PC via USB. Without special drivers, it emulates a USB Keyboard when attached. Users can open Notepad, attach the NEO, then hit a key to "upload" their document by having it type out the letters one by one. There is also a NEO Manager application, and special drivers, which allow two-way communication. This is used to update firmware or flash new "SmartApplets", the name for programs that execute on the NEO.

    There are multiple versions of AlphaSmart hardware: the 3000 is the oldest in the series, then the NEO, and the NEO 2 (which is like the NEO except it includes a proprietary radio system to link other NEO 2s in a classroom setting). There is also the Dana, which is actually a PalmOS device and very different.

    All told, there hasn't been much done on the hacking front. Users do a fair bit of case modding by repainting with vinyl dye. Someone has cracked the font format and produced a font editor (http://tsoniq.com/software/legacy/neo-fonts/). Most SmartApplets are distributed by the now-defunct manufacturer: there are two commercial apps "Co:Writer" and "Inspiration Outliner" that have long since passed out of their customer service life, and not a lick of homebrew code to be found.

    Yet.