natnet.protocol.common

Utilities for protocol package.

Copyright (c) 2017, Matthew Edwards. This file is subject to the 3-clause BSD license, as found in the LICENSE file in the top-level directory of this distribution and at https://github.com/mje-nz/python_natnet/blob/master/LICENSE. No part of python_natnet, including this file, may be copied, modified, propagated, or distributed except according to the terms contained in the LICENSE file.

class natnet.protocol.common.MessageId

Message IDs for each NatNet message (as in NatNetTypes.h).

Variables:

• Connect – Request for server info
• ServerInfo – Motive version, NatNet version, clock frequency, data port, and multicast address
• RequestModelDef – Request for model definitions
• ModelDef – List of definitions of rigid bodies, markersets, skeletons etc
• FrameOfData – Frame of motion capture data
• EchoRequest – Request server to immediately respond with its current time (used for clock sync)
• EchoResponse – Current server time (and time contained in EchoRequest message)

class natnet.protocol.common.ParseBuffer(data)

Buffer handling logic.

Contains a buffer and an offset, and provides methods for unpacking data types (as struct.Struct instances) from the buffer.

skip(struct_type, n=1)

Skip n fields of the given type.

unpack(struct_type)

Unpack a field.

Parameters:struct_type (struct.Struct) – Type of field to unpack

unpack_bytes(size)

Unpack a fixed-length field of bytes.

unpack_cstr(size=None)

Unpack a null-terminated string field.

If size is given then always unpack that many bytes, otherwise unpack up to the first null.

class natnet.protocol.common.SerDesRegistry(implementation_types=NOTHING, version=Version(major=3, minor=0, build=0, revision=0))

Registry of message implementations, which can serialize messages and deserialize packets.

An instance of this is used to provide the module-level function.

deserialize(data, version=None, strict=False)

Deserialize a packet into a message instance.

Parameters:

• data (bytes) – A NatNet packet
• version (Version) – Protocol version to use when deserializing
• strict (bool) – Raise an exception if there is data left in the buffer after parsing.

Returns:

Message instance

static deserialize_header(data)

Deserialize a packet into message ID and payload.

Parameters:data (bytes) – A NatNet packet Returns:tuple[MessageId, ParseBuffer] – Message ID and raw payload

deserialize_payload(message_id, payload_data, version=None, strict=False)

Deserialize the payload of a packet into a message instance.

Parameters:

• message_id (MessageId)
• payload_data (ParseBuffer) – raw payload
• version (Version) – Protocol version to use when deserializing
• strict (bool) – Raise an exception if there is data left in the buffer after parsing

Returns:

Message instance

register_message(id_)

Decorator to register the class which implements a given message.

Parameters:id_ (MessageId)

static serialize(message)

Serialize a message instance into a binary packet.

Parameters:message – A message instance Returns:bytes – The message serialized as a packet, ready to be sent

class natnet.protocol.common.Version

NatNet version, with correct comparison operator.

Believe it or not, this is performance-critical.

Variables:

• major (int) –
• minor (int) –
• build (int) –
• revision (int) –

classmethod deserialize(data, version=None)

Deserialize a Version from a ParseBuffer.

serialize()

Serialize a Version to bytes.

natnet.protocol.common.deserialize(*args, **kwargs)

Deserialize a packet into a message instance.

Parameters:

• data (bytes) – A NatNet packet
• version (Version) – Protocol version to use when deserializing
• strict (bool) – Raise an exception if there is data left in the buffer after parsing.

Returns:

Message instance

natnet.protocol.common.deserialize_header(*args, **kwargs)

Deserialize a packet into message ID and payload.

Parameters:data (bytes) – A NatNet packet Returns:tuple[MessageId, ParseBuffer] – Message ID and raw payload

natnet.protocol.common.deserialize_payload(*args, **kwargs)

Deserialize the payload of a packet into a message instance.

Parameters:

• message_id (MessageId)
• payload_data (ParseBuffer) – raw payload
• version (Version) – Protocol version to use when deserializing
• strict (bool) – Raise an exception if there is data left in the buffer after parsing

Returns:

Message instance

natnet.protocol.common.register_message(*args, **kwargs)

Decorator to register the class which implements a given message.

Parameters:id_ (MessageId)

natnet.protocol.common.serialize(*args, **kwargs)

Serialize a message instance into a binary packet.

Parameters:message – A message instance Returns:bytes – The message serialized as a packet, ready to be sent