Apple Accessory Protocol

From iPodLinux
Jump to: navigation, search 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.

Contents
[hide]1 Request/Response Structure 2 Mode List 3 Mode Switching (Mode 0) 4 Voice Memo (Mode 1) 5 iPod Remote (Mode 2) 6 Advanced Remote (Mode 4) 6.1 Type Bytes 6.2 Picture Blocks 7 Nike+ (Mode 9) 8 Credits

Request/Response Structure
The request and response messages follow this general form. Request/Response Message field header length mode command size 2 1 1 2 0xFF 0x55 size of mode + command + parameter the mode the command is referring to the two byte command optional parameter, depending on the command value

parameter 0..n

checksum 1

0xXX - (8 bit additive checksum) ( 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 0x00 0x01 0x02 0x03 0x04 0x09 Purpose Mode switching Voice Recorder Simple Remote Request Mode Status AiR Mode Nike+ Mode

Mode Switching (Mode 0)

Mode 0 Commands Command 0x01 0x01 0x01 0x02 0x01 0x04 0x03 Purpose Switch to Voice Recorder mode (not working on 5G) Switch to iPod Remote mode Switch to AiR mode Get current mode status

(response) the current mode number (0xXX is the mode returned by the iPod), 0x04 0x01 could also be an indicator that the iPod is currently busy - I frequently get this 0x04 0xXX skipping tracks very fast --- this info is not 100% correct, Im getting different responses. Will try to work this out later. 0x05 0x06 Switch to AiR mode (same as 0x01 0x04?) 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 0x01 0x00 0x01 0x01 Purpose Recording has started. 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 0x00 0x00 0x00 0x01 0x00 0x02 0x00 0x04 0x00 0x08 0x00 0x10 0x00 0x20 0x00 0x40 0x00 0x80 0x00 0x00 0x01 0x00 0x00 0x02 0x00 0x00 0x04 0x00 0x00 0x20 0x00 0x00 0x40 0x00 0x00 0x80 0x00 0x00 0x00 0x01 0x00 0x00 0x00 0x04 0x00 0x00 0x00 0x08 0x00 0x00 0x00 0x40 Purpose Button Released Play Vol+ VolSkip> Skip< Next Album Previous Album Stop Play (just play, no pause) Pause (just pause, no play) Mute (toggle) Next Playlist Previous Playlist Toggles Shuffle Toggles Repeat Ipod Off Ipod On Menu Button

0x00 0x00 0x00 0x80 0x00 0x00 0x00 0x00 0x01 0x00 0x00 0x00 0x00 0x02

OK/Select Button Scroll Up 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. Mode 4 Commands Command 0x00 0x00 Parameter (bytes) Result(1) Command(2) Result(1) Command(2) none 8 bytes none 1 byte 1 byte Purpose think that the result 0x04 means that the command wasnt understood 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. perhaps a simple ping-request ?! 0xFF 0xFF 0xFF 0xFF 0x00 0x00 0x00 0x00 (echo?) ? returns flag set with 0x00 0x0b, dont 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 or 0x01 parameter 0x00 & 0x01 result in a success-answere (copare 0x00 0x01), dont know what happens - seems to be a flag which can be read with 0x00 0x09

0x00 0x01 0x00 0x02 0x00 0x03 0x00 0x09 0x00 0x0a 0x00 0x0b 0x00 0x0c 0x00 0x0d

?(1) the 2-5 bytes of the parameters is the position in the play list. ?? results (4)position ?(2) in a answer 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 mainPlaylist - *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 0x00 0x13 0x00 0x14 0x00 0x15 0x00 0x16 0x00 0x17 0x00 0x18 0x00 0x19 none 2 bytes none ? Get iPod Type Size ? Gen3 20GB: 0x01 0x02 (0x01 = Gen3 iPod, 0x02 = 20GB ??) Gen4 30GB: 0x01 0x09 Gen5 30GB: 0x01 0x09 Get iPod Name

namestring(var) iPod Name as a null terminated string none type(1) number(4) type(1) number(4) Switch to the main library playlist (playlist 0) Switch to item identified by the number and type given. Get Count of the given types (count of playlists, etc) Amount of requested type returned 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. 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). Get time and status info Track length in milliseconds, elapsed time in milliseconds, status=0x0 stop, 0x01 playing, 0x02 paused Get current position in playlist Current position in playlist Get title of a song number title returned as a null terminated string Get artist of a song number Artist returned as a null terminated string Get album of a song number Album returned as a null terminated string

type(1) 0x00 0x1A number(4) number(4) 0x00 0x1B number(4) string

0x00 0x1C none length(4) 0x00 0x1D time(4) status(1) 0x00 0x1E none 0x00 0x1F 0x00 0x20 0x00 0x21 0x00 0x22 0x00 0x23 0x00 0x24 0x00 0x25 0x00 0x26 position(4) number(4) string number(4) string number(4) string

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 0x00 0x28 number(4) number(4) time elapsed on current song 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) AiR Playback Control. Play/Pause=0x01, Stop=0x02, Skip++=0x03, Skip--=0x04, FFwd=0x05, FRwd=0x06, StopFF/RW=0x07 Get Shuffle Mode Returns current Shuffle mode: Off = 0x00, Songs = 0x01, Albums = 0x02

0x00 0x29

command(1)

0x00 0x2C none 0x00 0x2D shufflemode(1)

0x00 0x2E shufflemode(1) Sets the shuffle mode. Off = 0x00, Songs = 0x01, Albums = 0x02. 0x00 0x2F none 0x00 0x30 0x00 0x31 0x00 0x32 0x00 0x33 repeatmode(1) repeatmode(1) Picture Blocks none Get Repeat Mode Returns current Repeat mode: Off = 0x00, One song = 0x01, All songs = 0x02 Sets the repeat mode. Off = 0x00, One song = 0x01, All songs = 0x02 Upload Picture for AiR mode (see picture block description below) ? Get Max Screen Size for Picture Upload ? Gen3 20GB: 0x00 0x78 0x00 0x41 0x01 => 120 x 65 ? 0x00 0x34 2+2+1 bytes Gen5 30GB: 0x01 0x36 0x00 0xa8 0x01 => 310 x 168 ? what means the 0x01 at the end? - perhaps the supported resolution for 1bit bitmaps Get number of songs in current playlist Number of songs in current playlist Jump to specified Songnumber in the current playlist type and number in ?main? playlist to filter by for calls to 0x0 0x18 and 0x0 0x1A. Acknowledge with 0x0 0x1. Seems to be invokable only after certain sequences: Switch Main Playlist (0x0 0x16)-> Names (0x0 0x1A). ?? Gen5 30GB: 0x01 0x36 0x00 0xa8 0x02 0x01 0x36 0x00 0xa8 0x03 ... some similarities to 0x00 0x34 perhaps different solutions for different colordepth?

0x00 0x35 0x00 0x36 0x00 0x37 0x00 0x38

none number(4) number(4) type(1) number(4) ??? (1)

0x00 0x39

2*(2+2+1) = 10 bytes

Type Bytes
Some of the commands refers to type bytes. These are as follows: Type bytes Type 0x01 0x02 0x03 0x04 0x05 0x06 0x08 Purpose Playlist Artist Album Genre Song Composer Podcast

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 number of the block (starting from zero) always 1, only in the first block width of the picture, only in the first block height of the picture, only in the first block number of bytes you will send for each line. Divisible by 4, and only in the first block 3 lines? of pixels to be displayed, every 2 bits represents a pixel (4 color greyscale) block number 2 unknown width height 1 2 2

bytes per line 4 picture bytes N

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).

Nike+ (Mode 9)
Mode 9 is apparently used to transmit information and commands associated with the Nike+ product line. Commands can be transmitted to or from the ipod. All data is at 57600 with 8N1 formating. Two types of commands have been observed; those which are commands to/from the receiver, and data from the wireless sensor. Packets containing data from the wireless sensor have additional structure inside their payload. Mode 9 Commands Command 0x00 0x00 0x07 0x07 0x00 0x25 0x05 unknown unknown unknown unknown 0x0D 0x0D 0x01 Direction To ipod Purpose Confirm / Acknowledge / OK, no payload

To receiver Initialization, no payload To receiver Enter linking mode, no payload To receiver Exit linking mode, use this sensor (based on WU paper) To receiver "I am ipod serial number" (based on WU paper) To ipod To ipod To ipod "I am receiver serial number" (based on WU paper) "I am listening for sensor serial number" (based on WU paper) Received wireless data: complex payload

The received wireless data payload is formated as 4 bytes, unique sensor id 22 bytes, data (structure unknown at this time)

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.