An accepted job is not a letter on paper
Our handwriting machine answers “accepted” to jobs that never reach the paper. Here is how that showed up, and what we check before we call a letter written.
Draft for review. Not yet approved for publication.
Our machine is a UUNA TEK iAuto-01 that holds a pen and writes on A4 sheets and envelopes. The vendor software has to run on a Mac or Windows computer next to it, and our own software sends it jobs through that computer. The interface for this is not documented, so we found out how it behaves by using it.
Most of what we learned is about one sentence: the machine said yes, and nothing was written.
What “accepted” means
When we send a job, the interface answers with error: 0. That means the job was accepted. It does not mean the pen moved.
On 13 August we found three ways this goes wrong:
- Phantom successes. After a job was cancelled, or while the machine was disconnected, a new job still got
error: 0and the progress counter went up. No pen path was created and nothing reached the paper. - A silent disconnect. When the machine drops off, the status call returns an empty list instead of an error. A program that reads an empty list as “nothing to do” walks away from a dead machine.
- Finished jobs stay in the list. After a sheet was written and lay in the tray, the task count still said 1. Anyone waiting for it to reach 0 waits forever.
What we trust instead
The one signal that moved when paper was really written was a progress counter. It went from 0 to 1 to 2 over two runs. So our agent notes the counter before it sends a job and then waits, for up to three minutes, for the number to rise. It borrows the idea from a printer's page counter.
The counter is not enough on its own. It also rose during the phantom successes. We cross-check that a job file of real size exists for the task. And the counter resets after every reconnect, so we only compare values from the same connection.
Five rules we use now
- Done means the counter moved, and a job file exists. A reply of “accepted” does not count.
- Read every reply strictly. On our first dry run a 404 page from a gateway parsed as valid JSON. The count came back undefined, and the agent reported “nothing to do” without ever reaching the queue.
- Empty the machine's queue before every job. We trusted a “clear” flag once. It did not remove a finished job that was still listed, and the machine wrote the old job again onto the envelope that had just been loaded for the new one.
- Only cancel what you created. On 9 and 10 September every A4 letter we sent directly stopped after 10 to 70 seconds. We spent a day suspecting the paper sensor, the format and the settings. The cause was our own envelope agent, which cancelled all open jobs every minute. The one-line scripts we used to send letters did the same thing before sending. Now each sender remembers its own task IDs and touches nothing else.
- Exclude what was already posted. At the first real run the queue showed 222 envelopes instead of 6. The other 216 belonged to letters that were already in the post. We now filter them out before anything is queued.
The same lesson, earlier
We learned the first version of this from a laser printer on 29 July. It accepted jobs and printed no sheet. Since then we treat every machine the same way: a job is finished when something on the other side has physically changed, and a message is not that.
If you build around a plotter
Write down what “done” means for your machine before you write the sender. Find a counter, a file or a sensor that only changes when work happened. Test it by sending a job to a disconnected machine and see whether your program notices. Ours did not, the first time.