Robix Software Tutorial

Usbor (model 32i) Robotic Servo Controller

Connect servos 1-6 to positions 1-6 on connector 'A'. Make sure to have the yellow/orange wire on 'top', as shown in the All Cables this Orientation legend, below right. Plug the USB cable into connector 'J' and into the computer. Connect power. (These steps may be done in any order.)

Usbor-32i Software

On your host computer (Win XP/2000 or Mac OS X, with PC-Linux coming soon) start both the Nexus and Nexway programs, in either order.

The Usbor software consists of two main programs, the Nexus and the Nexway which communicate via TCP/IP, the 'language' of the internet. Having two programs linked this way allows remote operation because the Nexus and Nexway (Nexway = 'Nexus Gateway') may be on different computers on the same LAN. Or the Nexus and Nexway may be running on two separate computers anywhere on earth as long as both computers are connected to the internet.And finally, the Nexus and Nexway may be run on the same computer, as we'll be doing in this tutorial.

As an example of remote operation, let's assume that connected to computer #1 via USB we have one or more Usbors. Each Usbor controls its Pods, which are groups of servos and sensors that have their own command stream. (Put another way, a Pod is typically either a complete robot, or an independently controlled 'organ' of a more complex robot. For instance, each arm on a multi-arm robot might have its own command stream, making each arm a Pod.) Computer #1 also runs the Nexus program that sees and operates all of these Usbors and their Pods. The Pods themselves are user-defined, and their lists of servos and sensors are stored in the flash memory of each Pod's Usbor.

On computer #2 we run the Nexway . The Nexway on this computer communicates with the Nexus (back on computer #1) via TCP/IP. A Pod Gui (graphical user interface, pronounced goo'-ee) application, which uses a Nexway, is also provided for Pod scripting and monitoring.

User Programs (in Java, C++, Visual Basic.Net) gain control of Pods by loading the Nexway and using it to relays commands and receive sensor information. 
Pod Gui's and User Apps load Nexway classes...   
The Nexways then link via TCP/IP to a Nexus class running on the same or a different computer... 
One Nexus links via USB to all Usbors connected to the Nexus's computer... 
Each Usbor's flash memory contains user-configured Pod (aka robots, aka organs...) 
The Nexus Gui is shown at right. You can see that it has detected a single Usbor connected to the computer, with serial number beginning 3MU.

Notice the configuration. It is named 'classic'. This is the factory configuration (the Config Id doesn't matter right now).This configuration is called 'classic' because it mimics the setup of the original controller for the Rascal construction set which had 6 servo outputs, 2 digital outputs, and 8 analog inputs. The 'classic' configuration has this same setup, but there are 4 copies so that 4 different Rascal projects could be run at one time from one Usbor.		 Usbor Nexus 
Here is the Nexway gui. Initially it is not yet connected to any Nexi (nex'-ee, plural of Nexus) and so we first click the 'New Nexus Connection' button to bring up the window below.  Nexway (no focus) 
New Nexus Connection  In this tutorial we will connect to the Nexus that is already running on our computer by selecting local host. Notice that we could also connect to a Nexus running anywhere else on the internet by entering its IP address here instead, and provided that firewalls allow the connection. Press OK to make the connection. 
After pressing OK, open the list of Pods in the Usbor. the Nexway gui now should look like the image at right.

Double-clicking on Pod1 opens a Pod gui, shown below. 		  

Your First Script

We start with an empty script panel. Notice that this is the script for Pod1 of the Usbor 3MUCYKMVDH6, or just Pod1 of 3MU for short.

Now type in these two script lines


move all to -1000; wait 5; digout 1 on, 2 off; wait 5
move all to  1000; wait 5; digout 1 off, 2 on; wait 5

Now run the script by clicking the 'run' button at upper left.

Note: If you get an error which indicates that the '1' after digout is invalid or out of range, your Usbor may not be configured to have any digouts (digital outputs). In this case remove both 'digout...;' statements up to and including the ';' and continue with the tutorial.

Click again to run the script again.

Your First Macro

Now turn the two script lines into a script macro named osc by altering the script to this form:

Note that the osc 4 line could also have come after the macro definition instead of before it.

Run this script as before () and see that osc runs 4 times. If you change the 4 to 0 and run the script, you'll see that osc runs indefinitely. After osc has repeated several times, stop the script by clicking anywhere in the script area, or by clicking on the red stop button .

Note that in general, you can have multiple commands on single line separated by ;'s. A ; is allowed at the end of a line but is not requied. Commands may not 'span' lines; that is, a command needs to start and end on the same line.

A script may contain any number of macros, and macros can call other macros.

Servo Current and Torque

Now apply gentle rotational pressure on the output shaft of servo 1 and watch the absi value of servo 1 increase as the servo draws more current to oppose the force you are exerting. The absi value is the absolute value of the short-term (~.1 second) average of the servo current. This value, in general, indicates the torque being exerted by the servo.

Teach Mode

Next, postion the text cursor on the word 'end' at the end of the macro and open the Teach Window by clicking on the teach button ''. You should notice an arrow, '->', appear in a new blank line above 'end'. In addition, the teach window will appear:

  While the Teach window has focus, your keyboard is acting as a teach pendant. That is, holding down various keys, as indicated in the window, will move the corresponding servo by coarse or fine increments in the positive or negative direction. If you have a servo properties panel on your Pod gui, and if servo position is shown, you will see the position change. 

After you have moved the pod's servos to new positions, click on the 'Add to Script' button in the Teach window, and a move command will be inserted on the line with the '->' arrow and the arrow will move down a line. Repeat these steps to add several new lines to the osc macro, then run the script again to see your added move commands in action.

Editing Scripts to Change Servo Parameters

Commands that alter servo properties need to be edited into the script by hand. In the macro osc, change the speed of the motion, add the command

maxspd all 5

as the first line in the macro, and then run the script again. You'll see that the motion is slower than before.

By the way, instead of running the script with the button, you can also double-click on the osc 0 line to run the osc macro indefinitely.

You can also adjust other servo properties assuming that these servo properties were defined as 'variable' in the pod's configuration. This brings us to the next section.

Usbor-32i Firmware and the Config Editor

Notice what happens when you add the line

minpos all -1500

to the script, and then double-click the line to execute it.

An error message, Servo property is read-only, appears in the panel near the bottom of the Pod gui as you can see in the image above. The reason for this error message is that the pod configuration stored in the Usbor, declares that minpos cannot be changed by a script command. This brings us to the next topic in this tutorial.

Usbor Configuration

The Usbor configuration is stored in the flash memory of the Usbor itself. The configuration defines how the 32 servo outputs (each of which can alternately be a digital output or 'digout') and the 32 analog inputs are assigned to various pods in the Usbor. Since the memory available in the Usbor for its configuration is limited, not all options can be turned on all the time.

Let's build a new configuration. In this example we will use 18 of the 32 servos, and make three pods of 10, 5 and 3 servos each. And all servos will have all of their properties adjustable by script commands. We begin by clicking the 'Configuration' tab on the Usbor Nexus gui.

Next click Open Usbor Configuration Editor and get

We start with 1417 bytes of ROM (flash) memory and 1824 bytes of RAM for our configuration. At present, the configuration holds only pod defintions, but in the future other features may be added to the Usbor firmware that also use configuration memory. Users will be able to update firmware via downloads from Robix.com.

To configure our 3 pods of 10, 5, and 3 servos each, each with all servo properties 'variable' we highlight System_All_Var as shown. Then we click Configuration and have

We can see the shortcut keys to add a pod ( Ctrl+Shift+P) and to add a servo (Ctrl+Shift+S) since we want VT or 'velocity trapezoid' servos. So now we quickly add a pod and 1 servo using the appropriate keystrokes, and make sure that 'System_All_Var' appears in the parent servo box at top right. Then we add 9 more servos with Ctrl+Shift+S presses and the first pod is complete:

Similarly, we next press Ctrl+Shift+P to start a new pod and add 5 servos to it with Ctrl+Shift+S and then add the final pod with 3 servos:

Finally, we save the new configuration to file '10-5-3.rbxUsborConfig' by using the file menu, and then we send the configuration to our Usbor by clicking on the Download button and selecting an Usbor (there's probably just one) to which to download the configuration. A reset of the hardware by pressing the reset button just below the USB connector may be required.

Now if we look at the Pod1 gui, we'll see that it has automatically recognized the new configuration and shows data for it. First, right-click on the servo properties panel and click Select Properties. Then check the minpos and maxpos boxes and close the dialog box. Finally, double-click on the script line minpos all -1500 and note that the minpos values in the servo properties panel change appropriately.

One last point: If you now try to run the script, a syntax error will appear in the digout command. Number is out of range. - 1 This error appears because the new pod1 configuration has no digout's. So remove the digout commands and run the script to see that it is valid once again.

Customizing the Pod Gui

Since there are now no digout's or sensor inputs, you can actually remove those panels in the pod gui to make more room for other parts of the display. Right click on the sensors area and you will see

where we have already highlighted Remove This Panel. Click to remove the panel and then repeat this for the Digouts panel. The right click on any panel in the pod gui and click on Pack Window. The result is

Now let's move the panel that says idle and also the error log panel just to the right of idle to a position right under the scripting window. We do this by removing both panels and then adding them. Remove the idle panel and the error log panel, and then do Pack Window again. Here's what we get:

Next we right click on the script panel and split it to the South and once again do Pack Window. This gives us:

Note the short, empty panel below the scripting panel. Right click on it and split it East. Then right click on the left panel and Replace With Pod Action Right click on the right panel and Replace With Error Log. Finally, right click on any panel and Pack Window. Here is our final result:

If you would like to make this your new default pod gui, click on Gui and Save. If you would like to save this pod gui layout under another name, click Gui and Save As.