V0.x to V1 Migration Guide

Use this checklist when upgrading a controller from V0.x firmware to V1 firmware. The procedure is intended to protect the device configuration and to help update host scripts after the firmware change.

V1 is a new firmware generation, not a drop-in replacement for every V0.x configuration or host integration. The exact compatibility and installation procedure depend on the product model, hardware variant, and application.

Read What's new in firmware V1 for the new capabilities, then use this guide as the upgrade checklist. The main differences between V0.x and V1 page provides a side-by-side reference.

Key V0.x-to-V1 changes

TEC PID tuning migration

V1 replaces the V0.x pgain, igain, and dgain commands with kprop, tint, and tder. The control error is expressed in °C. kprop is expressed in V/°C on voltage-output products and A/°C on HTC200; tint and tder are time constants in seconds.

There is no direct numeric conversion from V0.x PID values: the V0.x error scaling and gain definitions varied by product, and igain and dgain were discrete coefficients rather than time constants. CTL200 and CTL300E users in particular should expect to retune because their earlier firmware used board-specific PID error units.

Start with product defaults or a known safe V1 baseline, then retune and validate the control loop for the connected thermal load and operating point. The stability tolerance ttol is expressed in °C in V1. V0.x CTL200 and HTC200 used a resistance-based tolerance in Ω, while V0.x CTL300E had no equivalent setting. The default V1 ttol is 0.01 °C. The standalone TEC PID Tuning Migration page remains available as a focused reference.

What to review

Review both the controller configuration and the software that communicates with it:

• product identification and hardware compatibility;
• saved configuration and calibration data;
• commands sent by host applications;
• response formats, status reporting, and error handling;
• communication timing and polling behavior;
• protection limits, startup behavior, and application-specific operating procedures;
• automation sequences and other functions that depend on controller behavior.

Do not assume that a V0.x configuration script or host integration can be transferred without verification.

Before flashing

1. Check that your exact product and hardware variant is supported by V1 firmware. Do not flash V1 firmware on an unsupported product.
2. Record the current V0.x identification and configuration before upgrading. At minimum, save the outputs of the V0.x identification, status, and configuration commands used by your scripts.
3. Keep a copy of the V0.x firmware file and the saved V0.x command outputs until the V1 upgrade has been verified.

Also record the temperature setpoint and operating limits, existing PID settings and control-loop sampling rate, temperature-stability tolerance and thermistor calibration, TEC output and protection limits, and other application-specific settings used by the system.

Flash the V1 firmware

Flash only the V1 firmware file that matches the exact product and hardware variant printed on the device label or reported by the device. Do not use firmware built for a related product, a different output option, or a different hardware variant.

After flashing, reconnect to the serial interface and verify the device identity:

>> IDN?
Koheron,CTL200-X-X-XXX,12345,V1.x
>> version
V1.x
>> serial
12345
>> model
CTL200-X-X-XXX

The IDN?, version, serial, and model responses must match the expected product, serial number, and V1 firmware version before operating the device.

Reapply the configuration

V1 does not convert a saved V0.x configuration into a valid V1 configuration. Reapply only the settings that are valid for the V1 product and your hardware setup. Do not blindly replay a complete V0.x script until each command and response has been checked against the V1 command API.

Review control settings before enabling outputs

Do not restore a complete V0.x configuration without reviewing the control-loop and output settings. Legacy TEC PID commands and units are not directly portable to V1; see the TEC PID tuning migration page before configuring temperature control.

Keep the laser and TEC outputs disabled while checking the migrated settings. Verify the sensor wiring, setpoints, limits, interlock state, and control mode before enabling the relevant output with tecon or lason. A valid command response does not replace checking that the connected load and operating conditions are safe.

If the device starts with unexpected output state or unstable control, set the CFG switch to 0 and restart to use the product default configuration. Reconfigure the device from that known baseline before saving it.

Save and verify the V1 configuration

Once the configuration and operating behavior have been reviewed, run save and record the returned CRC:

>> save
A1B2

In V1, save returns the saved configuration CRC. Update scripts that expected the old config saved text response.

Check ecrc after saving if your upgrade procedure records the saved configuration state:

>> ecrc
A1B2

The saved configuration is loaded at boot only when the saved configuration CRC is valid. Restart with the CFG switch set to 1 and confirm that the expected V1 settings were restored before returning the device to service. If the CRC is invalid, erased, or missing, V1 keeps the product default configuration active instead of loading the saved configuration.

Host-software migration notes

• V1 validates command arguments strictly. A rejected write leaves the previous setting unchanged and reports an error.
• save returns the saved-configuration CRC instead of the earlier config saved text response.
• Use errlist instead of hard-coding product-specific error positions. Common errors have stable bit positions in bits 0..17, and product-specific errors start at bit 18.
• Treat errors as a 32-bit mask. Hexadecimal responses may omit leading zeros; for example, 4 is mask 00000004.
• CMD_UNKNOWN is common error bit 2, mask 00000004. CMD_ACCESS_DENIED is common error bit 4, mask 00000010.
• Distinguish CMD_INVALID_ARG from CMD_ACCESS_DENIED: invalid shape, invalid value, or invalid runtime request reports CMD_INVALID_ARG; a valid write shape with insufficient user mode reports CMD_ACCESS_DENIED.
• save and reset are no-argument writes and require advanced mode.
• Use fmtlist for the full supported binary status field list. fmtlist is also the layout to use for full unmasked logerr snapshots.
• Use ecrc to inspect the saved configuration CRC after saving or during upgrade checks.
• Binary status is new in V1. Host software that used V0.x has no existing binary-status decoder to migrate; implement V1 field discovery and decoding with the V1 field list and mask.
• Prompts and echo may be absent during multiplexed UART operation or raw binary transactions. Host software must parse and pace those exchanges explicitly.

Update host scripts

Update scripts and test procedures for V1 command syntax and output formats before returning the device to service. Pay particular attention to commands that parse identification, status, errors, or saved-configuration responses. Use the V1 command API as the reference for command names, responses, and persistence behavior.