Protocol

LabRAD Protocol

Overview

This page describes the byte-level packet format of the LabRAD protocol. You will probably not need this information unless you are planning to implement your own LabRAD API for a currently unsupported programming language.

Endianness

Good news! The LabRAD Manager auto-detects the Endianness you use based on the first packet you send it! So, all you need to do is to chose whichever one is more convenient to you and be consistent in using it.
If you have no preference, use Little Endian, which is the native format of the Manager. That way the Manager can handle the data slightly faster.

Flattened Data

The entire LabRAD packet structure can be described as flattened LabRAD data. So, let's go over how the different Data Types are flattened, i.e. converted into their binary representation:

	Tag		Length [Bytes]		Description
	b		1		False: 0x00, True: anything else
	i		4		Signed 32bit Value
	w		4		Unsigned 32bit Value
	s		4 + len(s)		Flattened i giving length of String followed by raw String data
	v		8		Value in 64-bit double-precision format (Units are given in Type Tag)
	c		8 + 8		Flattened v for real part followed by v for imaginary part
	t		8 + 8		Signed 64bit Integer giving whole seconds since 12:00am, Jan 1, 1904 UTC followed by signed 64bit Integer giving fractions of seconds.
	_		0		Nothing
	(...)		0 + len(...)		Flattened cluster elements concatenated in order
	*?		4 + len(?)		Flattened i giving array length followed by elements concatenated in order
	*n?		4*n + len(?)		n flattened i's giving array lengths along n dimensions followed by flattened elements
	E		8 + len(error)		Flattened (is)
	E?		len(E) + len(?)		Flattened (is?)

Packet Structure

The unit of data transfer across the network is called a Packet. Apart from its payload, a Packet contains parameters, like where it is coming from or where it is going to, as well as its type (Request, Response, Message) and the Context in which it is to be interpreted.

	Field		Type Tag		Description
	Context		(w, w)		Gives the Context of the Packet
	Request		i		Gives the Request ID of the packet: >0 for Requests, =0 for Messages, <0 for Replies
	Src/Tgt		w		Gives the Source ID (incoming packets) or the Target ID (outgoing packets)
	Records		s		Flattened s containing flattened records concatenated in order

Record Structure

The data inside Packets is enclosed in Records. Apart from the payload, Records contain the Setting number that the data is meant for as well as the Type Tag of the data.

	Field		Type Tag		Description
	Setting		w		Gives the Setting ID that the data is meant for / came from
	Type Tag		s		Gives the Type Tag of the data in this record
	Data		s		Flattened s containing flattened data

Example

A Packet for Server 1 (the Manager) in Context (0, 8) with Request ID 5 containing one Record for Setting 3 with String Data "Test Server" would be flattened to either (Big Endian):

00 00 00 00 00 00 00 08 00 00 00 05 00 00 00 01 00 00 00 1C 00 00 00 03 00 00 00 01 73 00 00 00 0F 00 00 00 0B 54 65 73 74 20 53 65 72 76 65 72

 
or (Little Endian):

00 00 00 00 08 00 00 00 05 00 00 00 01 00 00 00 1C 00 00 00 03 00 00 00 01 00 00 00 73 0F 00 00 00 0B 00 00 00 54 65 73 74 20 53 65 72 76 65 72

 
Notice that "Test Server" is flattened by prepending the length (00 00 00 0B) to form the data content, which is in turn prepended by a length AGAIN (00 00 00 0F) when it is inserted into the Record. Yes, we could have left out the length of the data in the Record, since it should be clear from the Type Tag and the Data how long the data should be, but including it does not make the packet significantly bigger, but makes the implementation of the unflattening function much easier and more reliable. Not only does this allow for more efficient memory allocation and easier lazy parsing, but the (un-)flattening functions used for the data types can immediately be used to handle the packet structure as well. Also, a bit of redundancy can be helpful in detecting bugs in the implementation.

Protocol

This specification will deviate a little from what is usually seen in protocol definitions because of the way the components of a LabRAD setup are called. In this specification we will be talking about Server/Client Modules making connections to the Manager. In usual network language, the Server/Client Modules would be called a Client, while the Manager would be called a Server, since the Modules open the connection to the port that the Manager is listening on.

Connect

First, the Server/Client Module opens a TCP connection to the Manager computer on the correct Port (usually 7682). The Manager will accept the connection if the originating computer is on the list of allowed hosts, otherwise the connection is terminated.

It is the Client/Server Module's responsibility to send the first packet. This packet needs to be for Target 1 in any Context with a positive Request ID and no Records. The Manager uses the Target to determine the endianness used by the Client/Server Module.

The Manager responds with a packet from Source 1 in the same Context with the negative of the Request ID containing one Record from Setting 0 with the Password Challenge as String Data.

This is the ONLY Request in the LabRAD Protocol that is not followed up with a Reply that has the same Record structure!

Authentication

To log in, the Client/Server Module sends a packet in any context with any positive Request ID to Target 1 containing one Record for Setting 0 with the MD5 Hash of the Password Challenge concatenated with the Password as String Data.

The Manager responds with a packet from Source 1 in the same Context with the negative of the Request ID containing one Record from Setting 0 with either a Welcome Message as String Data or an Error Record.

Client/Server Selection

Next, the Manager needs to know whether the incoming connection will be a Client or a Server connection. For this purpose, the Client/Server Module sends a packet in any context with any positive Request ID to Target 1 containing one Record for Setting 0 with data of the form ws for a Client containing the requested Protocol Version (currently 1 for v2.0) and the Connection Name or wsss for a Server containing the Protocol Version and Server Name as well as a Description for the Server and Remarks.

The Manager responds with a packet from Source 1 in the same Context with the negative of the Request ID containing one Record from Setting 0 with either the Connection ID as a Word or an Error Record.

 

~ Markus Ansmann, Jan 17, 2008