Support & Documentation

What you need

• Python 3.12 or later
• A USB-to-RS485 adapter (FTDI or CH340)
• A ZT-100-C connected on the adapter’s A/B terminals

Check your Python version

Run python3 --version. You need 3.12 or later. On Debian or Ubuntu: sudo apt install python3 python3-venv python3-pip

Unpack the download

unzip zt100c-app.zip && cd zt100c-app

Create a virtual environment

Run python3 -m venv .venv then source .venv/bin/activate. Ubuntu 24.04, Debian 12 and later refuse to install into the system Python and fail with “externally-managed-environment” if you skip this, so the venv is not optional there. Your prompt should now start with (.venv).

Install the tool

pip install -e .

Serial port permissions

On Linux your user needs access to serial ports: sudo usermod -a -G dialout $USER. Log out and back in for it to take effect. macOS needs nothing here.

Run it

Run zt100c-app. Each new terminal needs the environment activated again first: source .venv/bin/activate

Connecting to a card

1. Plug the USB-to-RS485 adapter in
2. Wire A/B through to the ZT-100-C
3. Open the Connect page and pick the port — typically /dev/ttyUSB0, or /dev/tty.usbserial-* on macOS
4. Click Connect — the product name and firmware version appear once it answers

Logging

Measurement logs are written under ~/ztlogs/zt-100-c. The active log path is shown in the app while logging runs.

Troubleshooting

• “externally-managed-environment” — the virtual environment step was skipped. Go back and create it.
• No ports listed — check the adapter is enumerating: ls /dev/ttyUSB*
• “permission denied” on the port — your user is not in the dialout group yet, or you have not logged out and back in since adding it.