my motor does not move

Let's look at the first example. Imagine you get something like:

263.SPEC> mv t2f 5
Can't move UNUSABLE motor 0, unit 0, "t2f".
Motion canceled.

This is the first and most basic tool: spec provides simple, relatively short messages to report problems. spec tells you that the motor can not be moved because it cannot be used but... why? Why is that motor UNUSABLE?

Something you can do then is to ask spec to restablish all the connections to hardware by typing reconfig. Doing so it is a safe way to close all open devices, synchronize with the current situation and test communication with hardware. In our case:

264.SPEC> reconfig
Getting configuration parameters from "SPECD/spec/config".
Purported NSC200 on "/dev/ttys002" is unusable.

Error messages are provided on the spot when something goes wrong. As you can see another moment when spec provides important information is when the application starts up or when hardware checking is done with reconfig command or after the config editor has been quit. Remember to check and understand error messages at that moment too.

So, from that message, what else do we know now? It looks like something with the device where the motor controller is configured is not going well. Maybe communication is not possible for some reason. Is the device connected? Or maybe it is the first time we want to use that motor, we just added the controller in spec and we set the serial line device or the baudrate wrong.

There is one way to get much more detail information on the communication between spec and the device: by using the spec powerful debug tool.

289.SPEC> debug

Add values together to obtain a debugging level:

    1     0x1  Show input tokens during parsing.
    2     0x2  Show node execution while running.
    4     0x4  Show node allocate and free.
    8     0x8  Show symbol table creation and lookup.
   16    0x10  Show value get and set.
   32    0x20  Show misc memory-related info.
   64    0x40  Show hardware related info.
  128    0x80  Show more hardware related info.
  256   0x100  Show macro substitution.
  512   0x200  Show memory allocate and free.
 1024   0x400  Show input after macro expansion.
 2048   0x800  Print warning messages.
 4096  0x1000  Show certain low level hardware info.
 8192  0x2000  Show data array allocation.
 ...   0x4000  Show signal blocking.
 ..    0x8000  Show low level hardware info.
 .    0x10000  Show input file queuing.
 .    0x20000  Show readable runtime debugging.
 .    0x40000  Print input context on execution-time errors.
 .    0x80000  Show sleeps.
 .   0x100000  Show thread stuff.
 .   0x200000  Show state changes.
 .   0x400000  Use hexadecimal for socket debugging output.
 .   0x800000  Show server/client socket messages.

Debug value (0xc0)? 192

I have selected the debug value 192 that is the sum of the options 64 and 128. In that way we will get all hardware related information available. You see that there are many selectable debug options in spec. Once you know the option that most interests you, you could directly select it by typing (in our case):

debug 192

Then spec gets then really much more verbose:

285.SPEC> reconfig
mot_sync(1, 0x100, -1)
mot_sync(136, 0x100, -1)
mot_sync(174, 0x100, -1)
Closing serial communication line /dev/ttys002.

Getting configuration parameters from "SPECD/spec/config".
Config file:
 PSE_MAC_MOT = tab3 20
Macro Hdw controller, unit 0, 20 channel(s).
Config file:
 CONPAR:d1 = 1240
Config file:
 CONPAR:d2 = 343
Config file:
 RS_NSC200 = /dev/ttys002 300 8
Opened /dev/ttys002 at 300 baud raw
NSC200/PZC200 controller, unit 0, 256 channel(s).
Config file:
 SW_SFTWARE = 1 POLL
Config file:
 MOT000 = NSC200:0/0   2000  1  2000  200   50  125    0 0x003      t2f  Front
NSC200/PZC200 motor, unit 0, channel 0.
NSC200 send: 0VE?\r
SERIAL send a=20 b=0 s=<0VE?\r>
SERIAL get  a=20 b=0 \n\r
SERIAL select timed out
NSC200  read error (-2).
Purported NSC200 on "/dev/ttys002" is unusable.
[...]

The debug can fill your screen with literally hundreds of lines. We will see in a minute how to handle this. But before that, in our example, you can see the exchange that happens between spec and the motor controller that ends up in the initial unusable message.

NSC200/PZC200 motor, unit 0, channel 0.
NSC200 send: 0VE?\r
SERIAL send a=20 b=0 s=<0VE?\r>
SERIAL get  a=20 b=0 \n\r
SERIAL select timed out
NSC200  read error (-2).
Purported NSC200 on "/dev/ttys002" is unusable.

spec has tried to send the command "0VE?r" to the motor controller. You could check now if the message corresponds with the documentation (otherwise maybe we chose the wrong controller type in the configuration). In any case there is no response to the command. That suggests that the device is not connected, not switched on, or other communication problem is happening. There we are. We have gone 90% in the way of solving the problem. You can now leave spec alone and check the hardware controller and connections.

When you finish with the debugging, you can switch the tool off by typing.

debug 0

As I mentioned above if the number of messages on the screen gets really too big, you have the option to redirect them to a text file where you could handle them conveniently.

on("/tmp/spec.dlog")

The .dlog extension tells spec to save debugging information in that file instead of showing it on the screen.

IMPORTANT: once you have finished debugging do not forget to close the file and stop the debugging tool.

291.SPEC> close("/tmp/spec.dlog")

292.SPEC> debug 0

Otherwise spec will continue sending messages to that file. It can get really BIG!

scan is slow, it has too much overhead

Maybe you have heard somebody saying: spec is so slow, my scan takes ages to complete.

Definively not, spec is not slow. Even if computers are fast and full of resources today, everything in spec is done to be efficient from the software point of view, saving memory usage or CPU cycles. This was of crucial importance more in the past than it is today. But, more important, spec is efficient in accessing hardware. Okay, computers are fast, but... are you sure the hardware communication is fast? For example, serial lines and GPIB are relatively slow by today standards. For this reason, spec pays special attention to access the hardware only if necessary.

For example, the position of a motor is only read if it has moved, or if it requires a move. It is possible for the user to specify that a certain motor has to be read everytime spec reports motor positions but the default is that it will be only read if necessary.

Still, if you feel that your scan is slow it is really because it IS slow. Why?

once in a while my scan stops for no reason

setscans

when trying to move a motor another one moves

that good macro I wrote for my experiment does not work anymore

macro expansion. debug 0x40000

that good macro I wrote for my experiment does not work anymore

simulation

that good macro I wrote for my experiment does not work anymore

disable and on/off feature

Tools and techniques to gather error information in spec

So. You have seen above some of the techniques to gather information and to solve problems. Let´s now list them one by one.

390.FOURC> reconfig

Getting configuration parameters from "SPECD/fourc/config".
Unconfigured GPIB controller (unit 0).
MM2000/3000 - Write error sending "VE\r".
Purported MM2000/3000, unit 0 at GPIB 7, is unusable.