PearlLib and Tools

As described in the protocol overview, each message sent is of a specific type. The known types are documented below, along with their request/response formats and quirks.

The protocol messages documented here were found in one of two ways:

1. They were captured by my network analyzer during my initial traces.
2. They were found in the packetTypes.properties file in the Rio Media Manager Lite distribution.
3. In the case of NAK and Busy, they were pointed out by the KarmaLib folks. (Note [2 Jan 2003]: I've now captured Busy messages in the wild and they're documented here, as well as some of the Write-related messages.)

The part of the protocol that comes closest to being consistent is the message header. As mentioned above, each message begins with a 64-bit header, consisting of the protocol signature and the message type.

The protocol signature is always Hex 52 69 c5 8d.

The message type is specific to the type of message (yay tautologies!) and is a 32-bit little-endian integer. In the listing of types below, I've specified the message types as a sequence of four bytes in the order that the bytes are transmitted on the line.

The eight-byte sequence of (signature || message type) is abbreviated as "message header" in the descriptions below.

Protocol Version

This message appears to be used to exchange protocol versions of both the Client and the Karma.The interpretation of the fields as "major" and "minor" versions is supported by the Karma's protocol type as reported by UPnP: "empeg-com:protocol2".

The Karma doesn't seem to actually do anything with this message. Sending "2.0" gets the same response as sending "2³².2³²", and omitting the message entirely doesn't seem to hurt. I suppose, primarily, this exchange is for the benefit of the client software, not the Karma.

Example

52 69 c5 8d  signature
00 00 00 00  message type (Protocol Version)
02 00 00 00  major version (2)
00 00 00 00  minor version (0)

NAK

Progress

This message is sent by the Karma to report progress on a lengthy task. In the case of my packet captures, RMML sends a Release Database Lock immediately after uploading new file info; the Karma sends Progress messages until it finishes updating the file info, and only then responds to the Release Database Lock message.

Example

52 69 c5 8d  signature
0a 00 00 00  message type (Release Database Lock)

52 69 c5 8d  signature
02 00 00 00  message type (Progress)
00 00 00 00  current progress
20 00 00 00  goal

52 69 c5 8d  signature
02 00 00 00  message type (Progress)
01 00 00 00  current progress
20 00 00 00  goal
...
52 69 c5 8d  signature
02 00 00 00  message type (Progress)
20 00 00 00  current progress
20 00 00 00  goal

52 69 c5 8d  signature
0a 00 00 00  message type (Release Database Lock)
00 00 00 00  status (here, indicates success)

Get Salt

This message asks the Karma for salt to use when hashing the user's password. (Salting the password prevents a block replay attack on the authentication exchange.)

The salt appears to be valid for only one Authenticate message. Each time a new password is attempted, a new salt must be retrieved. This is only logical.

Example

52 69 c5 8d  signature
03 00 00 00  message type (Get Salt)

52 69 c5 8d  signature
03 00 00 00  message type (Get Salt)
b1 ab 51 c0  \
de 16 fb 2e   | salt
ca c4 01 d4   |
80 fc 59 4a  /

Authenticate

This message should follow an Get Salt request, and provides the Karma with a salted hash of the user's password.

The Karma responds with a status value (zero or positive on success) and the type of access (0 for read, 1 [01 00 00 00] for write).

The type of access granted should be considered undefined if the status indicates failure.

The salted hash is simply the the MD5 of the sequence (salt || password) -- that is, the salt (16 bytes) followed by the password (1+ bytes). While the Karma does not appear to allow zero-length passwords, the RMML client sends one before actually requesting a password from the user.

Example

52 69 c5 8d  signature
04 00 00 00  message type (Authenticate)
30 97 c7 75  \
f7 52 d4 17   | salted password hash
8c bf 52 6b   |
79 0d 93 55  /

52 69 c5 8d  signature
04 00 00 00  message type (Authenticate)
5b 00 04 80  status (here, indicates failure.)
00 00 00 00  access type (0, read, but really undefined due to failure)

Get Device Info

This message provides the most general information about the device. The name returned probably reflects the internal name of the system software; the version returned most certainly reflects the firmware version installed. The most useful aspect of this message (and the one piece of data not available anywhere else) is the number of storage devices.

Note that this message does not carry a status field.

Example

52 69 c5 8d  signature
05 00 00 00  message type (Get Device Info)

52 69 c5 8d  signature
05 00 00 00  message type (Get Device Info)
6f 6e 79 78 00 00 00 00 \
00 00 00 00 00 00 00 00  | device name (here, "onyx")
00 00 00 00 00 00 00 00  |
00 00 00 00 00 00 00 00 /
31 2e 32 35 00 00 00 00 \
00 00 00 00 00 00 00 00  | version (here, "1.25")
00 00 00 00 00 00 00 00  |
00 00 00 00 00 00 00 00 /
01 00 00 00  number of storage devices (here, 1)

Get Storage Device Info

This message retrieves information on one of the Karma's storage devices. Since the Karma only has one, the Storage Device Number in the request should always be zero.

Number Of Files and Highest File ID in the response are both marked with question marks, because I haven't been able to verify their use. (The Karma, as of firmware 1.25 and earlier, always sends zero in these fields.)

For me, the Karma takes about three to four seconds to respond to this command.

Example

52 69 c5 8d  signature
06 00 00 00  message type (Get Storage Device Info)
00 00 00 00  storage device number (for the Karma, always zero)

52 69 c5 8d  signature
06 00 00 00  message type (Get Storage Device Info)
00 00 00 00  status (here, indicates success)
00 00 00 00  number of files? (always zero)
00 a0 52 a3 04 00 00 00  total space in bytes
00 a0 c3 76 03 00 00 00  free space in bytes
00 00 00 00  highest file ID? (always zero)

Get Device Information

This message retrieves detailed information from the Karma. See the Property File documentation.

Example

52 69 c5 8d  signature
07 00 00 00  message type (Get Device Information)

52 69 c5 8d  signature
07 00 00 00  message type (Get Device Information)
00 00 00 00  status (here, indicates success.)
63 61 70 ....null-terminated ASCII text.

Change Device Settings

Get Database Lock

This message is used to obtain a lock on the Karma's file database. The lock can be for reading (type 0, hex 00 00 00 00) or for writing (type 1, hex 01 00 00 00).

The existence of two separate types of locks suggests that the Karma may support a many-reader, one-writer style of locking. I've verified that it supports multiple readers, at least.

Others have called this lock the "IO Lock;" the name "Database Lock" comes from the class names used within RMML and, I suspect, more accurately reflects its purpose.

Example

52 69 c5 8d  signature
09 00 00 00  message type (Get Database Lock)
00 00 00 00  lock type (0, read)

52 69 c5 8d  signature
09 00 00 00  message type (Get Database Lock)
5d 00 04 80  status (here, indicates failure.)

Release Database Lock

This message releases a lock previously obtained with an Get Database Lock message. There's not much more to it than that.

Example

52 69 c5 8d  signature
0a 00 00 00  message type (Release Database Lock)

52 69 c5 8d  signature
0a 00 00 00  message type (Release Database Lock)
00 00 00 00  status (here, indicates success.)

Prepare

Write

Writes to a file on the device. This is used when uploading new files. It probably also allows existing files to be modified, but this is a very unusual case with music files, and one I'll have to force artificially to verify.

It's worth noting that I've seen this command take upwards of 4 seconds to complete, even after the upload has finished.

Example

52 69 c5 8d  signature
0c 00 00 00  message type (Write)
00 00 00 00 00 00 00 00  offset (in bytes)
00 40 00 00 00 00 00 00  size of chunk (16384 bytes)
a0 58 00 00  file ID
00 00 00 00  storage ID
49 44 33 ... binary data, null-padded to multiple of four bytes.

52 69 c5 8d  signature
0c 00 00 00  message type (Write)
00 00 00 00  status (here, indicates success.)

Get All File Information

This message retrieves all file metadata from the Karma. The files do not appear to be in any particular order, not even the order in which they were loaded onto the device. Information on each file is in key-value pairs; see the Property File documentatin.

Example

52 69 c5 8d  signature
0d 00 00 00  message type (Get All File Information)

52 69 c5 8d  signature
0d 00 00 00  message type (Get All File Information)
00 00 00 00  status (here, indicates success.)
61 72 74 ....null-terminated ASCII text.

Get File Info

Change File Info

This message uploads new properties for a single file. The properties are in the same format returned by the Get File Info and Get All File Info messages; see the Property File documentation.

Example

52 69 c5 8d  signature
0f 00 00 00  message type (Change File Info)
80 46 00 00  file ID
64 75 72 ....null-terminated ASCII text.

52 69 c5 8d  signature
0f 00 00 00  message type (Change File Info)
00 00 00 00  status (here, indicates success.)

Read

Delete

This message deletes a file by FID. It requires a write lock, logically enough.

Example

52 69 c5 8d  signature
11 00 00 00  message type (Delete)
80 46 00 00  file ID

52 69 c5 8d  signature
11 00 00 00  message type (Delete)
00 00 00 00  status (here, indicates success.)

Format

Device Operation

Please read the disclaimer.