Use the Log, Luke!

Whenever you hit a problem, first thing to do is to check the daemon log. For this, switch the daemon into debug log level. The most convenient way to do this is from the config tab in the web UI, where you can also easily retrieve the log. But you can also set the log level when starting the daemon:

LOG_LEVEL=debug oqtactl serve -d /dev/ttyUSB0 [other options]

If you’re running the daemon as a systemd service, you need to edit the unit file accordingly, and restart the service. For many problems, the daemon log should already give you good hints about what’s going on. It’s also important when reporting an issue over at the project home at Codeberg.

Check the Online Help

The oqtactl binary provides online help for all actions. Just run oqtactl --help to get a list of the available actions, and oqtactl {action} --help for finding out more about a particular action. Maybe there are additional options that you weren’t aware of, and that can help you work around a problem.

Make Sure OqtaDrive Correctly Recognizes Your Machine

When the OqtaDrive adapter starts up, it auto-detects what it’s connected to, i.e. Interface 1 or QL, and configures itself accordingly. This may fail in certain situations, so it’s one of the first things to check. The daemon log and also the web UI show what machine has been detected.

In particular, after turning on the Spectrum, the adapter sometimes erroneously detects the Interface 1 as a QL. The cause is that the COMMS_CLK signal of the Interface 1 occasionally is at 0V after power on, while it should be 5V. The first Microdrive action taken then corrects this. To work around this problem, OqtaDrive rechecks the interface type at first drive activation and re-syncs with the correct type, if necessary. The first action will still fail, but the interface setting is now correct and all subsequent actions will succeed. So if you see your Interface 1 being detected as a QL, run a CAT 1, and a few seconds later, the problem should be corrected.

You can however also change the detected interface by re-syncing the adapter, either via the web UI or oqtactl resync. Both methods also allow you to force a particular machine, via a set of radio buttons or the --client option. If you’re always using the adapter with only one type of machine, you can also hard-code that in the adapter config. Check the config section at the top of oqtadrive.ino, and look for the FORCE_IF1 and FORCE_QL settings. You can also force a particular machine with the --client option when starting the daemon.

Tip: When using the adapter with a Spectrum + Interface 1, make sure to power up the adapter after or together with the Spectrum, but not before. Otherwise it will auto-detect a QL.

Common Issues

Check this list of common issues at the project home.

Check Reported Issues

If you can’t resolve the problem, have a look at reported issues at the project home. Maybe the problem you’re seeing has been reported before. If that doesn’t yield anything and you’re sure what you’re seeing is a bug, open an issue.