[SET pageicon help] [SET title The SLIMP3 Client Protocol] [SET techinfo 1] [INCLUDE helpheader.html]
Note: This document describes the previous version of the SLIMP3 protocol. This document will be updated to accurately reflect the current protocol. The SLIMP3 communicates using a custom UDP-based protocol. This protocol is designed to be extremely light-weight. It gives the server low-level access to the hardware and full control over the user interface, so as to mimize the amount of hardware and software required on the client side.
All packets are preceded by an 18-byte header. The first byte in this header is a token which indicates the format of the rest of the header. Some kinds of packets may have also have variable amount data of after the header. Variable length data is not delimited - the length is taken from the UDP header. All numbers are unsigned integers, in network order. The server listens on port 1069, and replies to the source port of the packets it receives from the client.
'D' - Discovery response
Field Value/Description 0 'D' as in "discovery" 1 reserved 2..5 server's IP address, or 0.0.0.0 6..7 server's port 8..17 reserved
On receiving a (d)iscovery request broadcast (see below) from a supported client, the server replies with a unicast (D)iscovery response, containing the IP and port number that the client should contact. If the server's IP address is left blank (0.0.0.0), then the client will instead get the IP address and port from the IP/UDP packet headers. A server replying to a discovery request may redirect a client to another server (for load balancing) using this mechanism. If multiple discovery responses are received, the client will select the first one it receives.
'h' - Say hello
Field Value/Description 0 'h' as in "hello" 1..17 reserved
This is used by the server to determine if previous known clients are up, and to obtain the model and firmware revision of those clients. Clients reply with another (h)ello, see below.
'l' - Send data to the lcd/vfd display
Field Value/Description 0 'l' as in "lcd" 1..17 reserved (ignored) 18... variable length string of 16-bit codes
The Noritake vacuum fluorescent display used in the SLIMP3 implements the standard Hitachi LCD interface, plus additional codes for controlling brightness. The data sheet is in CVS under docs/datasheets. The SLIMP3 protocol allows both "character data" and "commands" to be sent directly to the display. It also allows you to insert a delay between characters. This is used to insert the required delay after the "clear screen" command, and can also be used to create animated sequences. The delay feature is not currently used by the server, and probably shouldn't be used in its current implementation, because the player has to spin for the specified time and can not be interrupted. Instead, delays should be implemented in an interruptible manner on the server side.
The 16-bit codes are:
00XX, where XX specifies a delay in ms, up to 255 02XX, where XX is a command 03XX, where XX is one of the 256 characters supported by the display
's' - stream control
Field Value/Description 0 's' as in "stream" 1 One of three control codes 2 Delay in ms before executing the command 3..17 Reserved
This tells the player to start, pause, or unpause the stream. The three control codes are:
0x01 Reset the buffer and start a new stream 0x02 Pause playback 0x04 Resume playback 0x08 Enable buffer usage display (for debugging)
To synchronize multiple players, combine the "start" and "pause" codes (0x03) to tell the player to fill its buffer without playing anything. Then, send "resume" commands to each of the players to make them unpause the stream. You can specify a delay in ms before the command takes effect, if necessary.
If 0x08 is set, the SLIMP3 will display its buffer usage in the top left corner of the display, as an 8-bit hex value.
'm' - write MPEG data into the player's buffer
Field Value/Description 0 'm' as in "mpeg" 1 reserved 2..3 16-bit address to write into the player's 1Mbit buffer (16-bit words) 4..17 reserved 18.. variable length string of data (length must be even # of bytes)
The operation of the player's buffer and the workings of the streaming protocol are covered in the last section of this document, "Streaming".
'2' - read/write the i2c bus
Field Value/Description 0 '2' as in "i2c" 1..17 reserved 18.. string of i2c commands and data
The protocol allows the i2c bus to be manipulated down to the level of discrete start / stop / ack / nack / read / write operations. The data sent after the header is a string of these operations, specified as follows:
wX write the byte X onto the bus r read a byte from the bus s start p stop a ack n nack
The client acknowledges all i2c packets. See '2' under the "Client->Server" section.
Please see the Philips web site for more information on i2c. At the bottom of that page, you'll find the i2c spec sheet in PDF format.
'd' - Discovery request
Field Value/Description 0 'd' as in "discovery" 1 Device ID, '1' for SLIMP3 2 Firmware rev, eg 0x11 for version 1.1 3..17 reserved
This packet is sent to the broadcast address on port 1069. The client sends this during startup to discover the server's IP address, after the client has configured his own IP interface. The server replies with a unicast 'D' packet - see above.
'h' - Say hello
Field Value/Description 0 'h' as in "hello" 1 Device ID, '1' for SLIMP3 2 Firmware rev, eg 0x11 for version 1.1 3..17 reserved
The SLIMP3 sends a hello packet to the server when it first starts up, and whenever it receives a hello from the server. This is for the server to learn that a new client is ready, or for the server to query a client to see if here's still there.
'i' - IR code
Field Value/Description 0 'i' as in "IR" 1 0x00 2..5 player's time since startup in ticks @625 KHz 6 0xFF (will eventually be an identifier for different IR code sets) 7 number of meaningful bits - always 16 (0x10) for JVC 8..11 the 32-bit IR code 12..17 reserved
'r' - request stream data
Field Value/Description 0 'r' as in "request" 1 reserved 2..3 write pointer (client is requesting data starting at this address) 4..5 read pointer (decoder is currently reading out of the buffer at this address - not implemented yet) 6..17 reserved
'2' - i2c response
Field Value/Description 0 '2' as in "i2c" 1..17 reserved 18... string of bytes in response to the requested i2c read operations, if any
The SLIMP3's buffer chip is a 128K x 8 (1Mbit) SRAM. It is presented to the server as a 64K x 16 circular buffer. The SLIMP3 maintains two pointers, called rptr and wptr, which track the position at which the DMA controller is reading (out to the decoder) and writing (in from the network). When a new stream is started, the SLIMP3 begins by initializing an empty buffer, with rptr == wptr == 0. It then begins requesting data from the server, starting from 0. The server replies with some data, which the SLIMP3 writes into the buffer. Once the buffer reaches 50% capacity, the decoder is started, and the rptr begins to increment. The SLIMP3 continues requesting data until the buffer is 90% full. Oncee the buffer reaches this "almost full" state, the SLIMP3 continually checks buffer usage, requesting more data only when the buffer usage drops below the "almost full" level.
Timeouts due to a lost packet are handled by the client. It the SLIMP3 does not receive a response from the server after 100ms, then it sends the request again.
This is a pretty simple streaming protocol, intended only for use on low-latency networks. A future protocol will behave in a somewhat TCP-like fashion, with the server handling timeouts, maintaining multiple packets in flight, and taking responsibility for the client's buffer. The client will simply acknowledge each packet, instead of requesting data at a particular offset. The specification for the new streaming protocol (and why we don't just use TCP) will be discussed in another document.
ICMP
ICMP echo (ping): The SLIMP3 will send an ICMP response and display a message indicating where the ping came from.
ICMP unreachable: This indicates that the server machine is up, but the server process is not running. The SLIMP3 will display a message to the effect of "10.0.0.1: service unreachable - are you sure the SLIMP3 server is running?"
Other ICMP messages are displayed on the screen in a similar manner, but they are otherwise ignored (eg ICMP redirect does nothing, but the player will still tell you, so you know to fix your gateway setting).
UDP echo
The player will echo any packet sent to it on UDP port 7. This could be used to obtain an RTT estimate. Unlike ping, it does not cause anything to be displayed on the screen.
TCP - experimental/future
Doesn't do much right now. You can connect on port 23 but that's about it.
DHCP
[INCLUDE helpfooter.html]As of firmware version 1.1, the SLIMP3 can use DHCP to discover its own IP address.