Troubleshooting

When something fails, narrow the problem in this order: installation, host startup, channel open state, protocol response, point value, then UI binding.

Three Quick Checks

1. Replace the real channel with AddVirtualChannel to verify the application structure.
2. Print channel.State and confirm it reaches Open.
3. Print received bytes as hex before trying to parse text.

channel.DataReceived += (_, e) =>
{
    Console.WriteLine(Convert.ToHexString(e.Data.Span));
};

Installation and Packages

Symptom	Likely cause	Fix
dotnet is not found	.NET SDK is missing or PATH was not refreshed	Install .NET 8 SDK and reopen the terminal
Zeus package is not found	nuget.org is unavailable or the package name is wrong	Use dotnet add package Zeus.Communications
AddVirtualChannel is missing	Zeus.Communications is not referenced	Install the communication package
AttachZeus is missing	UI adapter package is missing	Use Zeus.Presentation.WinForms or Zeus.Presentation.Wpf
WinForms / WPF restore fails	Target framework is not Windows desktop	Use net8.0-windows

Host and Names

Symptom	Likely cause	Fix
Channel xxx cannot be found	Channels.Get uses a different name than registration	Compare with registered names in the exception
Channel name already exists	Two channels have the same Zeus name	Rename one, for example meterBus or plcBus
Current state is Created, cannot write	StartAsync was not called	Start the host first
Port stays busy after exit	Host was not disposed	Use await using or AttachZeus

Serial and TCP

Symptom	Likely cause	Fix
Serial open fails	COM port does not exist or is occupied	Check Device Manager and close serial tools
Serial opens but no data arrives	Wiring, baud rate, parity, or device behavior is wrong	Verify with a serial tool first
Received text is garbled	Binary protocol was displayed as text	Inspect raw hex bytes
TCP connect fails	IP, port, firewall, or listener is wrong	Confirm the port is reachable
Peer disconnects and channel becomes Faulted	TCP connection was closed	Default reconnect will retry, or call OpenAsync

Protocol-Specific Checks

Protocol	Common issue	First check
Custom frame	Timeout waiting for a complete frame	Header, length, checksum, and raw bytes
Modbus	Timeout or illegal data address	Unit id, RTU/TCP mode, 0-based address, CRC/MBAP
Mitsubishi MC	End code or timeout	Frame type, encoding, device code, address base
Siemens S7	Handshake or DB read failure	IP:102, rack/slot, DB access settings, byte/bit offset
Omron FINS	Timeout or end code	UDP/TCP port 9600, node numbers, network numbers
Omron Host Link	Timeout or FCS failure	Unit number, serial settings, ASCII @...*\r frame
EtherNet/IP	CIP status or timeout	TCP 44818, tag path, data type, external write permission

Points and Acquisition

Symptom	Likely cause	Fix
Point has no valid value	First poll has not succeeded	Subscribe to Points.Changed or use TryGet
Short point name is ambiguous	Multiple devices expose the same point name	Use device.point
UI shows an old value with an error	Latest poll failed; last successful value was retained	Inspect the point snapshot Error
Bus is overloaded	Polling interval is too short or addresses are scattered	Increase the interval and group addresses

JSON Configuration

Symptom	Likely cause	Fix
Config file not found	Working directory or copy settings are wrong	Check the absolute path in the exception
Channel is not declared	Device references a missing channel	Declare the channel before the device
Events disappeared after changing COM port	Hot reload rebuilt the channel instance	Get the channel again and resubscribe
Polling interval did not change	JSON is invalid or file watching is disabled	Check logs and watch: true

Still Stuck

Join the QQ group 771421105 and include:

• Zeus version and runtime environment.
• Channel type: virtual, serial, TCP, or UDP.
• Serial settings or network address.
• Raw sent and received bytes.
• Full exception message.
• For Modbus: unit id, function code, start address, and quantity.