Labrad data type - syue99/Lab_control GitHub Wiki

We give the credits to Labrad first-vers. Wiki

RPC Protocol

Labrad clients communicate by sending packets over the network. There are three types of packets: requests, responses and messages. Requests and responses always come in pairs and have remote-procedure-call (RPC) semantics: a client sends a request to a server and the server sends back a corresponding response. Messages can be sent at any time by any client or server to any other party in the system. These are typically used for asynchronous notifications, and usually require one party to sign up for notifications of some sort, e.g. notification that a server has connected to or disconnected from the sysstem, that registry directory has changed, or that new data has been added to a data set.

By Fred: For more details regarding the RPC protocol, check here. It seems that we are using requests and responses when servers requests parameters and when building the data pipelines. We need to understand the Labrad data type below as a lot of time you need to specify the data structure beforehand when transmitting data using this RPC protocol. An example can be found in the AWG section.

Labrad DataType and Encoding

Basic Types

Tag Description Encoding Notes
b boolean, true or false 1 byte canonically encoded as 0x00 (false) or 0x01 (true); any other non-zero byte should also be interpreted as true when decoding
i 32-bit signed integer 4 bytes
w 32-bit unsigned integer 4 bytes the tag w was meant to stand for "word", although this does not correspond to a CPU word, which will likely be 64-bit on most modern systems
s string of bytes 4-byte length + length bytes There is currently no separate type explicitly for textual data. Text encoded as s should use UTF-8. In the future this type will be exclusively UTF-8 text.
v or v[<unit>] 64-bit floating point 8 bytes, IEEE 754 see discussion of units below
c or c[<unit>] 128-bit complex number 8-byte real part + 8-byte imaginary part see discussion of units below
t timestamp 8-byte signed int (seconds since 1904-01-01T00:00:00Z) + 8-byte unsigned int representing fractions of a second this format originated with LabVIEW
y byte string 4-byte length + length bytes Future type for bytes/unicode disambiguation
_ empty data, the nil value 0 bytes typically only used at the top level, e.g. cannot be embedded in composite objects, a restriction inherited from LabVIEW

Composite Types

Composite types are built up from other types (basic types and other composites). In this table we use X, Y and Z to stand for valid type tags.

Tag Description Encoding Notes
(XYZ...) cluster of one or more data items cluster elements encoded one after another example: (v[m]s) represents a value with units of meters, followed by a byte string. This would be encoded as an 8-byte float, followed by a 4-byte length and then length bytes for the string.
*X or *nX 1- or n-dimensional array of elements of type X. n 4-byte integers giving the array shape, followed by all elements in row-major (C-style) order. In some cases, an empty array must be encoded and we do not know its element type. This will have a tag of *_ or *n_ and the size of the array (product of dimensions) must be 0.
EX error, consisting of an integer code, string message and extra "payload" of type X encoded just like the cluster (isX) where X is the payload type. Typically only appears at the top level in error responses, not embedded in other composite data structures.

Type Patterns

When describing what types are accepted by a remotely-callable server setting, one can specify a list of type "patterns" that describe the data types that are allowed. Any type tag is a valid pattern that matches exactly one type, itself. In addition, the special pattern ? matches any type.

We can also build up patterns by using this wildcard as part of a larger pattern, for example the pattern *2? would match a 2-D array with any element type.

Note that patterns are not themselves valid types. They are used as metadata to describe the set of allowed types that can be sent to a particular setting, but no data will ever have type ?, for example.

Tag/Pattern Annotations

Since type patterns are metadata meant to describe the data that can be sent to a server, they can also contain additional human-readable annotations to convey additional information, commas to separate cluster elements, and whitespace for clarity. In particular, curly braces can be used to include comments inline in type patterns, and anything after a trailing colon will also be interpreted as a comment. Also, if a top-level data item is a cluster, the outermost parens can be dropped. Hence, the following are all equivalent:

  • (ist)
  • ist
  • (i{number}, s{text}, t{time})
  • (i s t): number, text and time

In the current version of labrad and language APIs, the parsers for tags on data will accept this flexible format, even though it is primarily meant only for human-readable metadata on type patterns. This may change in the future, however.

⚠️ **GitHub.com Fallback** ⚠️