Skip to main content
U.S. flag

An official website of the United States government

Official websites use .gov
A .gov website belongs to an official government organization in the United States.

Secure .gov websites use HTTPS
A lock ( ) or https:// means you’ve safely connected to the .gov website. Share sensitive information only on official, secure websites.


Commands typed at the console are in bold and follow brackets >>>. Bracket pairs < and > are used to signify the type of input needed. Three dots ... means multiple inputs are possible. Hitting [Tab] on the keyboard will list available commands, devices, and nodes – typing part of a command, device, or node will narrow the list.

What are the most basic commands I need to know?

  • read

    • Reads the value(s) of the device(s) provided.
    • The read command is performed immediately and the results are posted to the console.
    • >>> read <device name> ...

    • EXAMPLE:
      • >>> read sampleAngleMotor

  • move

    • Changes the value(s) of the device(s) provided.
    • The move command is queued.
    • >>> move <device name> <value> ...

    • EXAMPLE: 
      • >>> move sampleAngleMotor 10

  • ct

    • Performs an individual count and writes the result to the console.
    • The ct command is queued.
    • >>> ct <keyword argument> ...

    • EXAMPLE:
      • >>> ct -t 10

What is the difference between display and read?

displaying a node will show node values based on the last state read from hardware.

reading a node will query hardware directly to get the latest value. If a node's value is based on other node's values, these other nodes will also be read, recursively.

Where can I find help about using a command or device?

In the menu, under Help-->Find/Help Commands and Devices. Type part or all of the name of the device or command into the help window.

What is the difference between the soft, hard, and raw positions?

  • rawPosition is the raw value as read from the hardware.
  • hardPosition is position in a convenient unit.
    • hardPosition = rawPosition × conversion factor
  • softPosition is further adjusted by a zero offset and to orient in a convenient direction.
    • softPosition = parity × (hardPosition – zero)

How can I set a motor’s position?

  • setMotorPosition
    • Conveniently redefines a motor’s softPosition by adjusting the zero.
    • >>> setMotorPosition <motor name> <softPosition value>
    • EXAMPLE:
      • >>> setMotorPosition sampleAngleMotor 10

How can I set a motor’s position without moving it?

  • Moving the resetRawPosition node for a motor will change the hardware readout of the motor itself (what NICE calls rawPosition).
    • >>> move <motor name>.resetRawPosition <rawPosition value>
    • EXAMPLE:
      • >>> move sampleAngleMotor.resetRawPosition 10

How do I restore lost motor positions (for example, after a power outage)?

Use the restoreMotorPositions command.

What does sleep do?

Use >>> sleep <# of seconds> to make the system wait a specified duration of time.

How do I change limits?

  • For motors, the softUpperLimit and softLowerLimit nodes define the limits.
  • For devices, such as temperature controllers, the upperLimit and lowerLimit nodes define the limits.
  • For controllers with multiple control channels, each channel has separate limits (upperLimit_1 and lowerLimit_1).
  • >>> move <motor name>.<limitNode> <positional value>
    • >>> move sampleAngleMotor.softLowerLimit 10
    • >>> move temp.upperLimit_1 150

How do I change units?

  • >>> setNodeProperties <device name>.<node name> --units <unit type>
    • >>> setNodeProperties sampleAngleMotor.softPosition --units rad


After units are changed, the latest units will not be reflected in all GUI panels until the client is restarted. The command line and Device Panel always respect the latest unit.

The dimension of a node CANNOT be changed. For example, if a node's unit was degrees you cannot change it to cm.

How do I lock (fix) a motor or other device? What is a lock?

  • A lock prevents a node from being moved directly or indirectly via a move command, trajectory, sequence, etc.
  • Everyone has permission to lock and unlock any node: >>> setNodeProperties <node> --userLocked true
  • Only admin can can admin-lock and admin-unlock a node:  >>> setNodeProperties <node> --adminLocked true

See: locking 

How do I know if the system is busy (motors moving, counting, etc)?

You can tell if the system is busy by looking at the top-right of any window in the status bar.

Go to Window > Device Control for real-time display of exactly which devices are busy. 



How do I add/remove sample environment equipment?

Go to Window > Configure Devices to add and remove available device configurations.

How do I stop ONLY the current command running in the queue?

Right-click the desired command in the queue and hit Cancel.


Cancel a command.

How do I find my files? How do I copy them from a previous experiment into the current experiment?

  1. Go to Experiment > View Experiment Manifest… to see all files organized by experiment. Search bar allows for experiments to be filtered.
  2. Selecting an experiment shows subfolders, including sequences and trajectories.  Right click and choose Copy on the files of interest.
  3. The current experiment is always at the top of the list.  You can also open a separate file browser by clicking Open Experiment Folder.
  4. Select the folder to be copied into (do not open the folder, right click on it) and select Paste files into /...

What is the difference between a script, a sequence, and a trajectory? How do I know which to use?

How do I customize output filenames in trajectories?

  • Sequences are a text file of NICE commands, executed in order.  No loops or if...then statements are allowed, but nesting other sequences is possible and any NICE command can be called from a sequence.  The easiest way to build a sequence is to select part of the queue and Copy, then Paste into a text file!  An editor with syntax-highlighting is built into NICE.  To learn more, go to Sequences.
  • A trajectory is the recipe for a “scan”, where data points are recorded to a data file.  It has syntax for supporting loops based on a “range” (e.g. start, step, stop) or a list of positions for a device to move to for each measurement. (Loops can be nested, scanning over e.g. a range of Q-values for a list of temperatures.)  To learn more, go to the Trajectory Guide.
  • A script is an embedded Python program, allowing the program to make decisions based on the results of measurements.  It is more difficult to make a script than the other two and is reserved for special circumstances (e.g., align a sample while cooling, but then move on with measurements when the setpoint temperature is reached). To learn more, go to Scripts.

How does temperature control in NICE work? What is hold time versus timeout versus tolerance band, etc?

To learn more about temperature controllers, go to Temperature Controllers under Sample Environment Equipment.

What are the different features of the counter? What is event mode versus non-event mode? Handshaking on versus handshaking off?

To learn more about counters, go to Counters.

How, where, and when to save configs, maps, and trays? Sequence files?

What are common file naming schemes?

To learn more about sequence and trajectory files, go to File Output under Sequences and File Output under Trajectory Guide.

To learn more about files used by VSANS, go to File Output under VSANS.

Created December 4, 2018, Updated June 9, 2023