Examples
Detect and Connect to Device
To communicate with your hardware, the library first needs an active communication channel. This is typically a serial port object that you create and configure. Example uses serial
You pass this communication object to the detect_device() function.
If a compatible device is found on that channel, the function will return a device object.
This object is your primary interface for all further interactions, such as sending commands and registering callbacks.
>>> from ptcc_library import detect_device
>>> import serial
>>> with serial.Serial('COM5', baudrate=57600, timeout=0.1) as ser:
>>> device = detect_device(comm=ser)
Register Callbacks
A callback is a function you write that is automatically executed when a specific piece of data arrives from the device. This allows you to react to incoming information asynchronously without having to constantly poll for it.
You link your function to a data ID using device.receiver.register_callback().
You can also pass an optional context argument, which is a static value that will be supplied to your callback every time it’s called.
This is useful for identifying the source or purpose of a measurement.
>>> from ptcc_library import CallbackPtccObjectID
>>> def name_callback(name):
print("Module Name:", name)
>>> def temp_callback(temp, context):
print(f"Temperature: {temp} K ({context})")
>>> device.receiver.register_callback(CallbackPtccObjectID.MODULE_IDEN_NAME, name_callback)
>>> device.receiver.register_callback(CallbackPtccObjectID.MODULE_BASIC_PARAMS_T_DET, temp_callback, "live")
Send Messages
The device object provides straightforward methods for sending commands and requests to the hardware.
These methods are typically named write_msg_*.
For example, write_msg_get_module_iden() requests the module’s identity information,
while`` write_msg_set_temperature() commands the device to change its temperature setpoint.
When the device responds to these messages, it will trigger the corresponding callbacks you have registered.
>>> device.write_msg_get_module_iden()
>>> device.write_msg_set_temperature(value_in_kelvins=230)
Handle Incoming Data
The library does not read from the serial port on its own. Your application is responsible for reading incoming bytes and feeding them to the library’s receiver for processing.
You must implement a loop to read data from your communication channel.
Each byte read should be passed to the device.receiver.add_byte() method. You can also use device.receiver.add_bytes() for passing multiple bytes.
This method processes the byte/bytes and returns a status. As it processes the data, it will automatically find complete messages and trigger any corresponding callbacks you have registered.
A return value of PtccMessageReceiveStatus.FINISHED indicates that a complete message has just been processed and its associated callback has been triggered.
>>> while True:
>>> byte = ser.read(1)
>>> if byte:
>>> if device.receiver.add_byte(byte[0]) == PtccMessageReceiveStatus.FINISHED:
>>> print("New message received")
Handle Containers
The device communicates by sending data in packets called containers. Each container holds a collection of related data objects. To process full data as it arrives, you must register a callback function that will be executed when a specific type of container is received.
Container IDs include:
DEVICE_IDENMODULE_IDENPTCC_CONFIGPTCC_MONITORMODULE_BASIC_PARAMSMODULE_LAB_M_MONITORMODULE_LAB_M_PARAMS>>> def iden_callback(objects): >>> for o in objects: >>> print(f"{o.name} = {o.value}") >>> device.receiver.register_callback(CallbackPtccObjectID.DEVICE_IDEN, iden_callback)