Most API elements described here are used when writing new device classes. They are defined in submodules of nicos.core, but re-exported in nicos.core for easier importing.
The nicos.core.errors module defines several exceptions that are used throughout the system. They are re-exported in nicos.core.
The following exceptions can be used when writing custom devices:
The basic exception class for exceptions raised by NICOS.
Every NicosError subclass has a “category” attribute, a string that is shown to the user instead of the exception class.
The constructor also accepts a Device instance as its first argument, which is then used to display the error to the user as coming from this device. For example:
def doRead(self):
if not self._ready:
raise NicosError(self, 'device is not ready')
The constructor accepts a the keyword wikicode with an integer argument to create a link to a wiki page
where more information can be given. The integer should be the Unix timestamp (e.g from date +%%s, to get a uniqe id) of the first use of this specific error. To create the wiki page, log in to trac and enter ‘wiki:NicosError/<integer>’ in the search box on the upper right.
Exception to be raised when the user gives an invalid value to a device (as a move target or parameter value).
Exception to be raised when user commands are used wrongly.
When this exception is caught by the user command handler, the help for the command that was executed is shown.
Exception to be raised when an error in the setup is detected, or a device is supplied with invalid configuration data.
Exception to be raised when an action is not allowed in the current execution mode.
Exception to be raised when an action is forbidden to the current user.
Used by the requires decorator.
Exception to be raised when an error in the code is detected.
This should not occur during normal operation.
Exception to be raised when a device detects an undefined position.
For example, this should be raised when several coders do not agree.
Exception to be raised when errors occur while moving a device.
Exception to be raised when a requested move target is out of limits.
Exception to be raised when some hardware communication fails.
Exception to be raised when a timeout waiting for hardware occurs.
This is not a communication timeout; for that purpose CommunicationError should be used.
Exception to be raised on fatal hardware errors.
Exception to be raised when a cache lock cannot be acquired.
The nicos.core.params module defines various helpers that are used when writing device classes. They are re-exported in nicos.core.
This class defines the properties of a device parameter.
The Device.parameters attribute contains a mapping of parameter names to instances of this class.
Attributes (equivalent to constructor arguments):
This class defines the overridden properties of a base class parameter.
The Device.parameter_overrides attribute contains a mapping of parameter names to instances of this class.
Overriding parameters allows to share parameters with the base class, but still have slightly different behavior for the parameters. For example, for a general Moveable device the unit parameter is mandatory. However, for some subclasses this will not be necessary, since the unit can either be automatically determined from the device, or the value never has any unit. Instead of redefining the unit parameter in subclasses, you only need to override its mandatory property in the subclass like this:
parameter_overrides = {'unit': Override(mandatory=False)}
The constructor takes all keywords that the Param constructor accepts. These properties of the parameter are then overridden compared to the base class.
This class defines the properties of the “value” read from Readable and Measurable classes. Their valueInfo method must return a tuple of instances of this class.
The categories allowed for Device.info() are:
These functions can be used to create parameter types (i.e. the type argument of Param) that not only convert to the correct type (such as int, str etc.), but also do more validation of the parameter.
Converter that accepts anything. Example:
Param(..., type=anytype)
Converter that only accepts valid TACO device names.
Converter that only accepts 3-vectors (i.e. lists or tuples) of floats.
Create a converter that accepts only integers in the range(from, to) (i.e., to is excluded).
Create a converter that accepts only floats between from and to. Examples:
Param(..., type=floatrange(0, 10))
Create a converter that accepts only None or what the converter accepts. Example:
Param(..., type=none_or(str))
Create a converter that accepts only one of the given values. Example:
Param(..., type=oneof('up', 'down'))
Create a converter that accepts only lists with element types given by the element_converter. Examples:
Param(..., type=listof(int))
Param(..., type=listof(tacodev))
Create a converter that accepts only tuples with element types given by the element_converters. Examples:
Param(..., type=tupleof(int, int))
Param(..., type=tupleof(tacodev, str, str))
Create a converter that accepts only dictionaries with key types given by key_converter and value types given by value_converter.
Create a converter that accepts only the keys and values of the dictionary given in values. When one of the keys is given, it is converted to the corresponding value. Example:
Param(..., type=oneofdict({'up': 1, 'down': 0}))
The nicos.core.status module defines the status constants that are used as the first item of the tuple that Device.status returns. The whole status module is re-exported in nicos.core.
The device is in a ready or idle state with no errors.
The device is in a busy state (moving or waiting for completion).
The device is a measurable in paused state.
The device has not reached its setpoint.
The device is in an error state.
The state of the device is not known.
A dictionary mapping these status values, which are integers, to their lowercased name (i.e., statuses[ERROR] == 'error').
The nicos.core.device module defines some decorators for device methods:
Decorator that marks a method as a user-visible method.
The method will be shown to the user in the help for a device.
Decorator to implement user access control.
The access is checked based on the keywords given. Currently, the keywords with meaning are:
The wrapper function calls Session.checkAccess to verify the requirements. If the check fails, AccessError is raised.
The nicos.core.utils module also defines some utility functions. They are re-exported in nicos.core.
Combine the status of multiple devices to form a single status value.
This is typically called in the doStatus method of “superdevices” that control several attached devices.
The resulting state value is the highest value of all devices’ values (i.e. if all devices are OK, it will be OK, if one is BUSY, it will be BUSY, but if one is ERROR, it will be ERROR).
The resulting state text is a combination of the status texts of all devices.
Wait for the device status to return exit the busy state.
delay is the delay between status inquiries, and busystates gives the state values that are considered as “busy” states; by default only status.BUSY.
Writing a custom user command is easy: just write a normal function and apply the usercommand decorator. The docstring of the function is the help for the command. A user command should raise UsageError when used improperly: the command help is shown automatically when such an error is raised.
In order to make user commands available in the NICOS namespace, they must be in a module that is mentioned by a modules list in a loaded setup (see Configuring NICOS: Setups).
Decorator that marks a function as a user command.