UDP - Free D Protocol


I was looking to find the right way to translate “a kind of” Free-D Protocol (http://docs.vizrt.com/tracking-hub-guide/1.0/description_of_the_freed_protocol.html)… hard way but with some helps we find it :

At the beginning I was looking to use some python’s code like this :

88 13 0 0       # Correspond to 4 bytes X value


001388         # Little endian





But I got some dropping values that might come from conversion problem… (see following pictures)

So A friend told me that values in 1 byte (“octet” in french) goes from 1 to 256. So we can do something like that :

88 13 0 0

Convert in decimal:

136 19 0 0


0 0 19 136

Multiply by 256

0 256256*256 + 0 256256 + 19 *256 + 136

Equal to


Be advise that you need to know the frame !

If anyone could explain me where I was wrong on the beginning…

Hope this will help someone :wink:

1 Like

Hi JulienL,
I’m a viz artist designer I don’t know about coding.
I have a tracker that can send tracking data to UDP socket and I’m finding a tool that can translate UDP data to FreeD protocol. Can you share your code ?

You might find the ‘struct’ python library and the unpack functions helpful. It can automatically convert data from a binary string into floating point or integer numbers.

For example, you can use this in the onReceive callback of a UDP In Dat to extract a float from the input

data = struct.unpack_from( “<f”, bytes, 0 )[0]


Also, do you have any examples of the UDP data coming from your FreeD tracker? We actually looked into implementing support for the FreeD protocol in TouchDesigner, but we couldn’t find any official documentation on it and the examples we had didn’t match that VizRT doc.


Hi @Prasith
I found the right code thanks a real developper that take a few hours with me for this. Like you I’m a visual artist.
May be the Robmc’s answer should be a nice try ! :wink:

All what I found is writted on my first comment :slight_smile: You should try this method too, this is just mathematics !

Hope it will helps you :slight_smile:

Thanks JulienL and rob.
Honestly I know nothing about coding. I just finding a ready to use tools.


Hey Julien, about to do the same… does the FreeD data arrive in XML, like that doc? How do you access it? Since it’s UDP, do you need to tell the camera/source to send data to you somehow? Is there a standard Port to connect with?

I believe the XML in that doc is just an internal format used by the vizrt software to describe how to read the data. The actual tracking data would come into TouchDesigner using the UDP In DAT as a string of bytes (0-255 numbers).

That document just descibes how to break up the data stream into the position and rotation data for the camera.

I’d be interested in hearing more about your setup if possible. As I mentioned earlier in the thread, we’ve been looking into adding native support for FreeD into TouchDesigner, but haven’t been able to find any very official docs on it. (If you can’t share details publicly, you’re welcome to e-mail me directly at robmc@derivative.ca).

Rob, found the protocol described as an appendix in a manual here:

That other doc seems to be some kind of description language only, as you said.

I’m firing up a camera soon and will report back.

Yeah, I think that is the one other reference I found to the protocol, but it didn’t seem to match with the only sample data I had been given.

Looking forward to hearing how your tests go.

Hi guys… wondering how this is going. Does anyone have a TOX they’d like to share? to be clear it converts into a FreeD stream correct? I’m hoping to convert NatNet into Free D to get into Disguise

@jreodica, you’re looking to generate a Free-D stream? I’ve got a test toe file that reads Free-D for controlling a camera inside touchdesigner, but I don’t know if anybody has tried sending free-d content yet.

However, it should be relatively straightforward to reverse the process in the attached file to encode the camera data and use a UDP Out Dat to send free-d messages using it’s python send function. I’m not very familiar with NatNet, but you should be able to grab the data from there whenever it changes or at a given sample rate.

This is the rough test file I had for reading free-d data:
freedTest.toe (5.8 KB)

1 Like

@robmc interesting stuff! I’ll check out this toe!..

in the meantime… here’s an idea of the NatNet data coming in from OptiTrack/Motive…

Table1 is the data format that FreeD is looking for?

Hmmm… I’ll have to do further research into the protocol before attempting to convert the Natnet. I have very little Python expertise mind you.

yes, those are the fields stored in a free-d message. The python functions inside udpin1_callbacks are extracting those numbers from the raw bytes.

The raw messages (which you can see in the udpin1 node), are 29 bytes long with the first byte being 209 or D1 in hex, and the last byte being a checksum value. Most of the values are 3 bytes (24 bits) long and the positions and angles use different multipliers to avoid decimals.

Let me know if you need anymore help, it sounds like an interesting project.

Joel, we’re doing the same, but we were just going to send OSC to disguise if at all possible.

I’m fine with python but buried in another project, but I’ll report back when we make some movement - hopefully next week.


Hi Bruce, it has been some months, but have you progressed on that issue?

I was planning to find a way to send FreeD Data out of a Coolux Widget Designer project. Unfortunately this thread is the only source I found which is at least bit helpful but I’m completely new to Touchdesigner and therefore a bit lost with just reversing Rob’s script.

FYI This thread is a bit old and now the experimental builds have a built-in FreeD CHOP to get your FreeD data into TouchDesigner without any scripting required, please check it out if you haven’t already.

@schlupp Just to confirm, are you looking to send or receive FreeD from TouchDesigner? As Ben mentioned, we’ve got the FreeD CHOP now to receive FreeD data, but we don’t have a system for sending it out of TouchDesigner yet.

If you’re looking to send, I did write a quick toe file for testing awhile ago that can send the raw bytes, but I haven’t written anything yet to encode those bytes from camera data yet. I’ve attached my sending project in case it’s useful, and I’d be happy to help you with the encoding script if you need it.

sendFreed.toe (5.8 KB)


Is there any info how to interpret the zoom and focus data? We have a Panasonic AW-UE150 PTZ and I haven’t figured out how to remap those freed values so that TDs cam matches the Panasonic

Unfortunately we don’t have any specific information on how panasonic encodes the zoom and focus data. I tried to contact them once for more information on their freed implementation, but never heard back.

My impression was that users were doing a linear interpolation between calibrations at min/max zoom values, but I’m not sure on the exact steps. Does the panasonic control software give the fov values or anything else?