Apple Accessory Protocol

From wikiPodLinux

The Apple Accessory Protocol is used for communication between the iPod and serially connected accessories (such as the Remote, iTalk etc). The protocol was introduced with the 3rd generation iPods, and at present it is assumed is also compatible with the 4th generation iPods and mini iPods. (The Dock Connector provides access to this communication channel as well.)

The connections uses a standard 8N1 serial protocol. The original speed rate is 19200 baud - higher rates (up to 57600 baud) work properly (tested the 5G) but make trouble sending large amounts of data (picture blocks) faster than 38400 baud.


Table of contents

Request/Response Structure

The request and response messages follow this general form.

Request/Response Message
field size value
header 2 0xff 0x55
length 1 size of mode + command + parameter
mode 1 the mode the command is referring to
command 2 the two byte command
parameter 0..n optional parameter, depending on the command
checksum 1 0x100 - ( (sum of all length/mode/command/parameter bytes) & 0xFF)

The mode in the message indicates which mode the command belongs to, these same mode values are used in the mode switching command below.

Mode List

List of Modes
Mode Number Purpose
0x00 Mode switching
0x01 Voice Recorder
0x02 Simple Remote
0x03 Request Mode Status
0x04 AiR Mode

Mode Switching (Mode 0)

Mode 0 Commands
Command Purpose
0x01 0x01 Switch to Voice Recorder mode, not working on G5
0x01 0x02 Switch to iPod Remote mode
0x01 0x04 Switch to AiR mode
0x03 Get current mode status
0x04 xx (response) the current mode number (xx is the mode returned by the iPod), 0x04 0x01 could also be an indicator that the iPod is currently busy - I frequently get this skipping tracks very fast --- this info is not 100% correct, I´m getting different responses. Will try to work this out later.
0x05 Switch to AiR mode (same as 0x01 0x04?)
0x06 Switch to iPod Remote mode (same as 0x01 0x02?)

Clearly there's stuff here waiting to be figured out.

Voice Memo (Mode 1)

The mode 1 commands are used for the voice recording functions. To initiate the recording mode on the iPod the send the switch to mode 0x01 command - this will switch the iPod display to the "Voice Memo" screen. When the record button is pressed the iPod will send the command "0x00 0x00", sending the command to switch to mode 0x01 will start the actual recording.

Mode 1 Commands
Command Purpose
0x01 0x00 Recording has started.
0x01 0x01 Recording has stopped (or paused).

iPod Remote (Mode 2)

The mode 2 commands are used by the remote control to signal button presses. When a button is pressed the appropriate code is send 66 times per second until the button is released at which point the button released command is sent.

Note that the 3 and 4 byte commands may not work for older (tested on a 3g) iPods. They are valid for newer (tested on an iPod Nano) iPods however.

Mode 2 Commands
Command Purpose
0x00 0x00 Button Released
0x00 0x01 Play
0x00 0x02 Vol+
0x00 0x04 Vol-
0x00 0x08 Skip>
0x00 0x10 Skip<
0x00 0x20 Next Album
0x00 0x40 Previous Album
0x00 0x80 Stop
0x00 0x00 0x01 Play (just play, no pause)
0x00 0x00 0x02 Pause (just pause, no play)
0x00 0x00 0x04 Mute (toggle)
0x00 0x00 0x20 Next Playlist
0x00 0x00 0x40 Previous Playlist
0x00 0x00 0x80 Toggles Shuffle
0x00 0x00 0x00 0x01 Toggles Repeat
0x00 0x00 0x00 0x04 Ipod Off
0x00 0x00 0x00 0x08 Ipod On
0x00 0x00 0x00 0x40 Menu Button
0x00 0x00 0x00 0x80 OK/Select Button
0x00 0x00 0x00 0x00 0x01 Scroll Up
0x00 0x00 0x00 0x00 0x02 Scroll Down

Advanced Remote (Mode 4)

The mode 4 commands are used for the Advanced iPod Remote (AiR) functions. The commands can be used to remotely control much of the iPod functions. Unfortunately when switched to this mode the iPod display changes to "OK to disconnect".

Commands you send to the iPod are in bold, responses to those commands from the iPod are not. The response is always the command + 1.

</table>

Type Bytes

Some of the commands refers to type bytes. These are as follows:

Mode 4 Commands
Command Parameter (bytes) Purpose
0x00 0x00 Result(1) Command(2) think that the result 0x04 means that the command wasn´t understood
0x00 0x01 Result(1) Command(2) Gives you feedback on the command you just executed. Result: 0=success, 2=failure, 4=you exceeded the limit of whatever you were requesting/wrong parameter-count, 5=sent an iPod-Answere-Cmd(?). The Command is the command that this is in response to.
0x00 0x02 none perhaps a simple ping-request ?!
0x00 0x03 8 bytes 0xFF 0xFF 0xFF 0xFF 0x00 0x00 0x00 0x00 (echo?)
0x00 0x09 none  ? returns flag set with 0x00 0x0b, don´t know, what this means (perhaps an indicator for track-change - if you set this flag to 0x01 it turns to 0x00 again after changing the track)
0x00 0x0a 1 byte 0x00 or 0x01
0x00 0x0b 1 byte parameter 0x00 & 0x01 result in a success-answere (copare 0x00 0x01), don´t know what happens - seems to be a flag which can be read with 0x00 0x09
0x00 0x0c 7 bytes  ??? results in a answer 0x0d
0x00 0x0d 11 bytes or 1 byte tried some parameters - result seems to dependent on current playlist
parameters 0x00 0x00 0x00 0x00 0x00 0x00 0x00 give (on my Ipod) 11 bytes
(0x00 0x00 0x00 0x00 0x00 0x00 0x02 0xf0 0xdb 0x00 0x00 in main-Playlist - *not* the playlist-number and *not* the count of tracks in this playlist)

This command can also inform the accessory when there is a track change (one song ends and another begins). So it is a "subscription" - some previous query caused the ipod to send this every time the track changes. Probably the parameter bytes are a kind of track ID, maybe based on some filesystem attribute, such as actual position on the hard disk.

0x00 0x12 none  ? Get iPod Type Size ?
0x00 0x13 2 bytes Gen3 20GB: 0x01 0x02 (0x01 = Gen3 iPod, 0x02 = 20GB ??)
Gen4 30GB: 0x01 0x09
Gen5 30GB: 0x01 0x09
0x00 0x14 none Get iPod Name
0x00 0x15 namestring(var) iPod Name as a null terminated string
0x00 0x16 none Switch to the main library playlist (playlist 0)
0x00 0x17 type(1) number(4) Switch to item identified by the number and type given.
0x00 0x18 type(1) Get Count of the given types (count of playlists, etc)
0x00 0x19 number(4) Amount of requested type returned
0x00 0x1A type(1) number(4) number(4) Get Names for a range of items, first number is starting item offset (0 for the first item), second number is number of items to retrieve. The iPod will send back an entire message for each item requested.
0x00 0x1B number(4) string offset, name of the item (note that playlist 0 is the "main library" and will contain all the songs on the iPod and have the same name as the iPod itself as in command 0x00 0x14).
0x00 0x1C none Get time and status info
0x00 0x1D length(4) time(4) status(1) Track length in milliseconds, elapsed time in milliseconds, status=0x0 stop, 0x01 playing, 0x02 paused
0x00 0x1E none Get current position in playlist
0x00 0x1F position(4) Current position in playlist
0x00 0x20 number(4) Get title of a song number
0x00 0x21 string title returned as a null terminated string
0x00 0x22 number(4) Get artist of a song number
0x00 0x23 string Artist returned as a null terminated string
0x00 0x24 number(4) Get album of a song number
0x00 0x25 string Album returned as a null terminated string
0x00 0x26 pollingmode(1) Start Polling Mode = 0x01, Stop Polling Mode = 0x00. Polling mode causes the iPod to return the time elapsed (0x00 0x27) every 500 milliseconds.
0x00 0x27 number(4) time elapsed on current song
0x00 0x28 number(4) Execute Playlist switch specified in command 0x00 0x17, and jump to specified songnumber in the playlist (0xFFFFFFFF = start at the beginning of the playlist, even when shuffled... probably what you want to use)
0x00 0x29 command(1) AiR Playback Control. Play/Pause=0x01, Stop=0x02, Skip++=0x03, Skip--=0x04, FFwd=0x05, FRwd=0x06, StopFF/RW=0x07
0x00 0x2C none Get Shuffle Mode
0x00 0x2D shufflemode(1) Returns current Shuffle mode: Off = 0x00, Songs = 0x01, Albums = 0x02
0x00 0x2E shufflemode(1) Sets the shuffle mode. Off = 0x00, Songs = 0x01, Albums = 0x02.
0x00 0x2F none Get Repeat Mode
0x00 0x30 repeatmode(1) Returns current Repeat mode: Off = 0x00, One song = 0x01, All songs = 0x02
0x00 0x31 repeatmode(1) Sets the repeat mode. Off = 0x00, One song = 0x01, All songs = 0x02
0x00 0x32 Picture Blocks Upload Picture for AiR mode (see picture block description below)
0x00 0x33 none  ? Get Max Screen Size for Picture Upload ?
0x00 0x34 2+2+1 bytes Gen3 20GB: 0x00 0x78 0x00 0x41 0x01 => 120 x 65 ?

Gen5 30GB: 0x01 0x36 0x00 0xa8 0x01 => 310 x 168 ?
what means the 0x01 at the end? - perhaps the supported resolution for 1bit bitmaps

0x00 0x35 none Get number of songs in current playlist
0x00 0x36 number(4) Number of songs in current playlist
0x00 0x37 number(4) Jump to specified Songnumber in the current playlist
0x00 0x38 none ???
0x00 0x39 2*(2+2+1) = 10 bytes  ?? Gen5 30GB: 0x01 0x36 0x00 0xa8 0x02 0x01 0x36 0x00 0xa8 0x03 ... some similarities to 0x00 0x34

perhaps different solutions for different colordepth?

Type bytes
Type Purpose
0x01 Playlist
0x02 Artist
0x03 Album
0x04 Genre
0x05 Song
0x06 Composer

Picture Blocks

Transferring a picture to the iPod's screen is done using picture blocks. A picture block is basically the picture command (0x00 0x32). It's complicated enough to deserve its own section.

The parameter bytes of a picture block look like the following:

Picture Block Parameters
field size value
block number 2 number of the block (starting from zero)
unknown 1 always 1, only in the first block
width 2 width of the picture, only in the first block
height 2 height of the picture, only in the first block
bytes per line 4 number of bytes you will send for each line. Divisible by 4, and only in the first block
picture bytes N 3 lines? of pixels to be displayed, every 2 bits represents a pixel (4 color greyscale)

An example would look something like the following:

First block:

0xFF 0x55 (standard header)
0x6E (length of data in this block)
0x04 (mode of the command)
0x00 0x32 (command for picture display)
0x00 0x00 (indicates the first block (block zero))
0x01 (damned if I know.. perhaps indicates that the size info for the picture is here)
0x00 0x78 (width of picture to be displayed)
0x00 0x40 (height of picture to be displayed)
0x00 0x00 0x00 0x20 (number of bytes you're sending for each line of the display - must be a multiple of 8 and has to fit the needed bits!)
The rest is a 4 color picture, with every two bits representing a pixel.
Checksum.

Second block and every block thereafter:

0xFF 0x55 (standard header)
0x65 (length of data in this block)
0x04 (mode of the command)
0x00 0x32 (command for picture display)
0x00 0x01 (indicates the second block (increment as you go))
The rest is a 4 color picture, with every two bits representing a pixel.
Checksum.

Any extra pixels you send outside the range of the picture size on the right or bottom of the picture then get cut off.

You can see if the command was valid when you watch the response string for each block.

Good response is 0xFF 0x55 0x06 0x04 0x00 0x01 0x00 0x00 0x32 0xC3.

Bad response 0xFF 0x55 0x06 0x04 0x00 0x01 0x04 0x00 0x32 0xBF.


Below a width of 0x10 fillbits are used (only every 4th nibble of the picturedata is taken for the picture).

Credits

The bulk of this information is due to the hard work by Christoph, you can find his results at http://stud3.tuwien.ac.at/%7Ee0026607/ipod_remote/ipod_ap.html. Generalisation of the results was the work of Otto, see http://ipodlinux.sourceforge.net/forums/viewtopic.php?p=3362#3362.

Views
Personal tools
Navigation


Toolbox