System Commands
Well, I guess that this is the moment we've all been waiting for.
We're going to see some real command examples here.
In fact the commands discussed here are the so-called System Commands.
System Commands differ in a few ways from normal commands.
All System Commands are pre-defined, which means that you may find most of them in all Slaves, and they all behave in a prescribed way.
Whereas normal Commands can be "invented" by the designer of the Slave to suit the needs of that Slave.
All System Commands start with an asterisk ( * ), while normal Commands must start with a letter from A to Z.
System Commands are the only Commands that can be executed while the Slave is selected by the General Call Address (255).
It goes without saying that the System Commands can also be executed while the Slave is selected by its own unique address, just like normal Commands can.
System Commands come in both flavours: Query Commands and Non Query Commands. It goes without saying that executing a Query Command while selected through the General Call Address has not much use because a Slave is not allowed to "speak" then.
A Slave doesn't necessarily have to know all specified System Commands. But the Commands it does know are to be executed the way I've described here.
Remember that the SB-Bus is Case insensitive, which means that you can use both upper or lower case characters in your Commands and Parameters.
*CATALOG?
Use: *CATALOG?
The selected Slave will answer by sending a list of all of its Commands, usually in alphabetic order.
Each Command is listed on a separate line.
As usual an OK prompt => follows at the end of the list.
This means that the *CATALOG? Command must be capable of handling Acknowledge Flow Control.
In fact it is the only System Command that will answer with multiple lines.
But to make it easier for the programmer I don't expect you to implement Acknowledge Flow Control if this is going to be the only Command that is going to use it.
However I would recommend that your Slave at least obeys the standard XON/XOFF Flow Control.
*ERROR?
Use: *ERROR?
The selected Slave will respond to this Command by sending a description of the error status of the previous Command.
It has not much use to request the error cause when the previous Command ended with an OK Prompt => or a Syntax Error Prompt ?>.
I bet you can predict yourself what answer is given by the *ERROR? Command then.
Things start to get interesting when the previous Command ended in an Execution Error Prompt !>.
Although you can often figure out yourself what went wrong in your particular case.
I've made up a list of some common error causes, which may be reported by the *ERROR? Command.
Don't expect this list to be complete though, you may add appropriate error messages to your Slaves if you feel the need for it.
In case you want to know the reason why a particular Command ended with an Execution Error Prompt you must give the *ERROR? Command immediately after the failing Command, before entering any other Commands.
Otherwise the previous error message gets lost.
You can ask for a particular error cause only once, because the *ERROR? Command itself erases the previous error cause.
The *ERROR? Command has one special property, it can't be placed in *HOLD. Please see the description of the *HOLD Command for further details.
*FAST
Use: *FAST
This Command is the counter part of the *SLOW Command.
It places the Slave in fast mode, which means that no extra delay is added after the Slave sends each CR character.
The fast mode is the default setting after a system reset.
This Command has become obsolete because computers are so much faster than when I first defined the SB-Bus protocol. Therefore this Command is now optional.
*FLOW
Use: *FLOW xoff|ack
This Command requires one parameter, which selects between XON/XOFF Flow Control only or a combination of XON/XOF and Acknowledge Flow Control.
The default after a system reset is XON/OFF Flow Control only.
The Parameter following the *FLOW Command must either be XOFF or ACK.
Please read the chapter about Flow Control for a more detailed description of the two available Flow Control modes.
*FLOW?
Use: *FLOW?
This Query Command will tell you what Flow Control mode is currently active in the selected Slave. One of the these two answers can be given:
XON/XOFF Only the XON/XOFF Flow Control is active. ACKNOWLEDGE Both XON/XOFF and Acknowledge Flow Control are active.
*HOLD
Use: HOLD
This Command activates the Hold mode, which means that the next Command will be placed in Hold and will therefore not be executed immediately.
A Command that has been placed in Hold can be started by executing the *TRIG Command.
The real strength of this procedure is when you place commands in Hold on multiple Slaves, and then execute the *TRIG Command while all Slaves are selected through the General Call address.
For instance you can take simultaneous samples with multiple instruments this way.
Because the *TRIG Command is usually given when selected by the General Call Address it implies that Slaves are not allowed to talk on the bus.
Therefore the Slaves must be able to buffer the samples internally for later inquiry.
The *HOLD Command is optional.
A Slave which is not interested in this Command (and therefore is also not interested in the *TRIG Command) should reply with an Execution Error.
The *ERROR? Command will then report the COMMAND NOT SUPPORTED ERROR.
At the same time not all the Slave's Commands may be placed in Hold.
Commands which don't want to be put in Hold can simply generate an Execution Error, which at the same time cancels the Hold mode.
The Command that directly follows the *HOLD Command will not be executed immediately.
It will be decoded including all of its parameters and then it is placed in Hold.
The Slave will send a normal status Prompt after it has placed the Command in Hold.
Because all parameters are decoded at this stage you may expect errors if any of the parameters is wrong or missing.
The Hold mode is deactivated when a Command generates an error.
A Slave will only accept the *TRIG Command when a Command is placed in Hold, which triggers the execution of the Command in Hold.
Any other Command given while a Command is placed in Hold will generate a HOLD MODE ACTIVE ERROR, which also cancels the Hold mode.
A Command which is placed in Hold is insensitive to new SB-Bus addresses.
This means that you may change the address as often as you like, without canceling the Command in Hold.
It goes without saying that the *HOLD Command itself can not be placed in Hold.
If you do send the *HOLD Command twice in a row it will deactivate the Hold mode again, generating an Execution Error.
The *ERROR? Command will then generate a HOLD MODE DEACTIVATED error.
Another exception is the *ERROR? Command.
This Command can't be placed in Hold either.
It will send the description of the last error cause, without disturbing the Command that was in Hold.
The Hold mode will be terminated if a new SB-Bus Address is received while no Command has been put in Hold yet. No error will be generated this time because the Slave is no longer selected after receiving a new address.
*ID?
Use: *ID?
This Command replies with the identity string of the selected Slave.
This is a string which holds the Slave's name and software version number and may be up to 32 characters long.
The Identity string will enable you to verify if you've selected the intended Slave.
*LOCS
Use: *LOCS
This Command allows the Slave to be controlled locally, from its front panel.
It is the counter part of the *REMS Command, which places the Slave in remote mode.
The local mode is the default mode of operation after a system reset.
The designer of the Slave may decide what local controls (if any) are to be locked when the Slave is in remote mode. This Command may simply do nothing when there are no controls on the Slave that can or may be locked out.
*REMS
Use: *REMS
With this Command you can place the Slave in remote mode. In remote mode some or all local controls of the Slave are locked. It's up to the Slave's design to determine which controls can or may be locked. An emergency button for instance is a good example of a control that shouldn't be locked.
Usually an indication on the front panel indicates when the Slave is placed in remote mode. The remote mode is especially suitable for automated measurements when operators are not allowed to change any settings.
The opposite Command of *REMS is the *LOCS Command, which returns the Slave to local mode.
*RST
Use: *RST
This is a mandatory command and is intended to allow easy resetting of the selected Slave or all Slaves together.
Resetting a Slave has the same effect as removing and restoring power to the Slave.
It is needless to say that a Slave that just performed a successful reset will no logger be selected, and thus cannot accept further commands until it is selected again.
This also implies that the Slave will not send a status Prompt back to the Master anymore.
You can also place this command in Hold on several Slaves to reset them later with a *TRIG command given to the General Call Address.
Although the *RST command is mandatory, it is up to the Slave whether it really resets itself or not.
Some Slaves which perform important functions (e.g. a Power Supply Unit) may choose not to allow a full reset.
But even if the Slave decides it is not going to perform a reset it should reset its SB-Bus interface.
This means that the Slave is no longer selected, is switched to Fast mode and the XON/XOFF Flow Control mode is selected.
*SLAVE
Use: *SLAVE address
This Command allows you to setup or change the SB-Bus address of a Slave. It goes without saying that this will only work if the Slave has some way of remembering its address in Non Volatile Memory. Slaves with a hard coded or hard wired address will not know this Command, because they have no way of changing and remembering their new address.
Actually this Command is intended for brand new Slaves which don't have a legal Address yet, although you may also use it to change the Address later on at any given time. It can also be used if you don't remember or don't know to which Address a specific Slave is responding.
In order to change the Address of a Slave you must first select it before you can give it the *SLAVE Command. By definition brand new Slaves have address 254 assigned to them. But what if you don't know the current Address of the Slave? Simple: Connect only that Slave to the bus and select it with the General Call Address, that way you're certain that it will listen. But remember, disconnect all other Slaves from the bus otherwise you may end up with multiple Slaves listening to the same Address.
You may give the Address parameter either in decimal or hexadecimal form.
Hexadecimal values are preceded by a Dollar symbol ($DE).
Feel free to omit the hexadecimal format if you don't like the trouble of coding it.
After all the *SLAVE Command is probably going to be used only once during the Slave's life time.
Make sure your software checks the validity of the given address before it is accepted.
You may accept values between 129 and 254.
I usually also accept values from 1 to 126, and internally add 128 to them (simply set bit 7 of the byte) before I do a range check.
*SLOW
Use: *SLOW
This Command is the counter part of the *FAST Command. It places the Slave in slow mode, which means that it will add an extra delay of 5 ms after each CR character.
This Command has become obsolete because computers are so much faster than when I first defined the SB-Bus protocol. Therefore this Command is now optional.
*STANDBY
Use: *STANDBY
This Command is optional, and only makes sense if the Slave can actually be placed in standby.
If a Slave can be placed in standby it may decide how deep it is going to sleep.
Some Slaves will only switch off their display and controls, while others may even partially or completely remove power from their circuits.
No matter how deep a Slave is going to sleep, there must always be a way to wake it up again with the *WAKEUP Command.
*TRIG
Use: *TRIG
This Command triggers, or in other words executes the Command that was previously put in Hold.
You can find more details about the Hold mode in description of the *HOLD Command.
You will get the most out of this Command if you set Commands in Hold on multiple Slaves and give the *TRIG Command while all Slaves are selected with the General Call Address.
As soon as the Command in Hold is executed by the *TRIG Command it will be removed from Hold, which means that you can never repeat the *TRIG Command.
If the Hold mode is not active at the time you give the Slave a *TRIG Command it will respond with an Execution Error.
The *ERROR? Command will then report the HOLD NOT ACTIVE ERROR.
If no Command is placed in Hold the *TRIG Command will also respond with an Execution Error.
In that case the *ERROR? Command will report the NOTHING IN HOLD ERROR, this will also terminate the Hold mode.
Please note that the *TRIG Command is the only Command that may reply by sending some data back to the Master. But this only happens if a Query Command was placed in Hold and the Slave was selected by its unique SB-Bus Address.
*TST?
Use: *TST?
The *TST? Command can be used to perform functionality tests of the Slave. It's up to the Slave what circuits or peripherals it is going to test and how it will report the results of the tests to the Master. A Slave may even not test anything at all, in which case it may respond with only the text OK followed by the OK Prompt.
*WAKEUP
Use: *WAKEUP
The *WAKEUP Command is not just an ordinary Command because it can only be given if the Slave is placed in standby mode by executing the *STANDBY Command. Therefore the *WAKEUP Command is only available on Slaves that support the *STANDBY Command. The *WAKEUP Command usually doesn't appear in a *CATALOG? listing, even if it is supported.
The wakeup procedure involves just a little bit more than just sending the *WAKEUP Command to the selected Slave.
The reason for this is that some Slaves may be in a deep sleep and it may take some time to get their attention.
Remember that a Slave can even switch off its processor entirely in standby mode, leaving no intelligence awake to interpret the *WAKEUP Command.
A Slave that can turn its processor completely down must wake its processor up when data is received on the bus.
This can easily be monitored by brief periods of low levels detected on the RxD line of the SB-Bus.
The Slave's processor must wakeup from its deep sleep within 3 seconds.
It doesn't have to be wide awake yet, and this state does not have to be noticeable on the outside.
It simply must be awake enough to accept its own address or the General Call address followed by the *WAKEUP Command.
If such a slumbering Slave does not receive its own address or the General Call address it may remain in a slumbering state until no more data is sent over the SB-Bus for about 10 seconds, after which it is allowed to fall back into a deep sleep again.
It may then forget that it has ever been wakened before.
It goes without saying that the Slave must wakeup completely if it did receive the *WAKEUP command.
The Slave will then perform a normal reset procedure, after which it is no longer selected.
Thus in order to communicate with a freshly awoken Slave you must select it again.
Please note that a Slave in standby will not reach a deep sleep while communication is taking place with other Slaves on the bus.
