Troubleshooting

Troubleshooting

Important

This page provides common diagnostic steps. The repository documentation and current command help are authoritative for exact options and behavior.

Collect the environment first

Record the software and scanner context before changing the system:

sdsctl --version
python --version
uname -a

For an SDS200 Ethernet connection:

sdsctl --host SCANNER_IP health
sdsctl -vv --host SCANNER_IP scanner-info

Include the scanner model and firmware reported by:

sdsctl --host SCANNER_IP info

USB scanner is not discovered

Inspect stable Linux serial-device paths:

ls -l /dev/serial/by-id/

Check whether the current user can read and write the resolved device:

test -r /dev/ttyACM0 && test -w /dev/ttyACM0 \
  && echo "Scanner is accessible" \
  || echo "Scanner is not accessible"

Use the project's optional udev rule when the device exists but the active user lacks access. Do not solve the problem by making the serial device globally writable.

Select a scanner explicitly when several devices are attached:

sdsctl --model SDS100 info
sdsctl --model SDS150 --port /dev/ttyACM0 info
sdsctl --model SDS200 \
  --port /dev/serial/by-id/SCANNER_DEVICE \
  info

SDS200 Ethernet discovery fails

Search only the directly relevant authorized network:

sdsctl discover \
  --network 192.168.0.0/24 \
  --network-only

Then test the known address directly:

sdsctl --host SCANNER_IP info
sdsctl --host SCANNER_IP health

Confirm that:

• the scanner and host are on reachable local networks;
• the scanner's Ethernet features are enabled;
• local firewall policy permits the SDS200 control and audio traffic;
• the address has not changed since a profile was saved.

Repair a stale profile through authorized discovery:

sdsctl profile repair PROFILE_NAME \
  --network 192.168.0.0/24 \
  --dry-run

Remove --dry-run only after reviewing the proposed repair.

TUI reports stale PSI data

The Textual TUI can warn about stale scanner-information updates and perform a rate-limited control reconnect. Enable informational logging to see the lifecycle:

sdsctl --log-level INFO --host SCANNER_IP tui

Read the canonical operational logging guide for expected recovery entries and configuration options.

SDS200 control recovery is independent from an active RTSP/RTP audio session, so an ongoing WAV recording should not be stopped by PSI recovery.

SDS200 network audio will not start

Stop other processes that may already own an SDS200 RTSP/RTP audio session. Examples include:

• another sdsctl audio process;
• a TUI session with active network audio;
• an Asterisk custom Music-on-Hold source;
• a validation or integration process.

Then retry a minimal recording:

sdsctl --host SCANNER_IP audio \
  --output /tmp/scanner-test.wav \
  --duration 10

Review the canonical network audio guide for transport behavior, reliability counters, Broadcastify, and Asterisk configuration.

Local playback fails

Confirm that the playback extra is installed in the active environment:

python -m pip install "sds200[playback]"

Test recording without playback to distinguish an RTSP/RTP problem from a local PortAudio problem:

sdsctl --host SCANNER_IP audio \
  --output /tmp/scanner-test.wav \
  --duration 10

If recording succeeds but --play fails, capture the complete playback error, operating system, audio backend, and selected output device.

Broadcastify-compatible encoding fails

Confirm that FFmpeg and libmp3lame are available:

ffmpeg -version | head -n 1
ffmpeg -hide_banner -encoders 2>/dev/null | grep -F libmp3lame

Keep source passwords out of command history and logs. Supply secrets through the documented environment-backed secret mechanism. Never attach an unredacted environment listing or Icecast authorization header to an issue.

Production Broadcastify testing requires an approved feed and the assigned Technicals settings.

Asterisk Music-on-Hold source fails

Verify that Asterisk can see the custom class:

sudo asterisk -rx "module show like res_musiconhold"
sudo asterisk -rx "moh show classes"

Use:

• an absolute path to the installed sdsctl executable;
• a profile readable by the Asterisk service account;
• format=slin;
• process-group termination for the custom source.

Inspect service logs with the system's normal journal tooling. Do not place a required executable or profile under a home directory the service account cannot traverse.

The canonical configuration is in the network audio guide.

Capture detailed diagnostics

Operational logs exclude raw scanner traffic by default:

sdsctl --log-level DEBUG --host SCANNER_IP monitor

Create a protocol trace only when needed:

sdsctl --trace scanner.trace --host SCANNER_IP monitor

Traces and captures can contain scanner names, channel names, unit identifiers, and network addresses. Review and sanitize them before sharing.

Open a useful issue

Before opening an issue:

1. Test the latest code from the default branch.
2. Search existing issues.
3. Run sdsctl health for the affected connection.
4. Capture a minimal reproducible command and complete error.

Include:

• installed package version or commit;
• Python and operating-system versions;
• scanner model and firmware;
• USB or Ethernet transport;
• exact command;
• complete sanitized error or traceback;
• minimal reproduction steps;
• whether another supported transport behaves differently.

See the repository support policy and GitHub Issues.