d.tools lite:

if your design requires a low level computer science approach, d.tools lite will give you a pure java interface to your hardware. the sample program dtools-lite-test outlines the three basics steps you need to know to get up and running with your program.

download dtools-lite from our sourceforge project page.


step 1: connect
dtools is connected to your PC using a COM port. You only need to know which COM port it is running.

first make sure you have theCP210x USB Driver installed. After installing the drivers, and connecting dtools to your PC, find the COM port number in the control panel in start->control panel->system->hardware->device manager

a window should popup listing all the devices on your PC. Under the PORTS section, look for CP210x USB. It should have a COM port number listed right next to it.

let's say it is 'COM3', connect to 'COM3' with the following call.
// create a port and try to open it // the port automatically tries to recover when you unplug or reset while running every 10 seconds port = new OSCSerialPort("COM3");
step 2: listen
your design should interact with the outside world using various devices that are provided by dtools.
each of these inputs have an address so they can be uniquely identified. You can choose to listen to a a specific device that you are using, or you have the option of using the power of regular expression to better match your desired devices.

the second parameter is a callback function which will be called whenever any of the assigned devices sends a message. You callback function must implement the acceptMessage method as show in step 4.
// listen to one specific input: //port.addListener("/in1",new TestListener()); //liste to only buttons port.addListener("/btn?",new TestListener()); // listen to everything port.addListener("/.*",new TestListener());
step 3: talk
you may also want to interact with dtools itself using certain devices provided by dtools. Once again, you need to identify the device by it's address, and just send it an integer valued message.

here is a quick sample function to send any address a byte value.
public void sendData(String address, byte value) { OSCMessage msg = new OSCMessage(); msg.setAddress(address); msg.addArgument(new Integer(value)); try{ port.send(msg); } catch (Exception e) { e.printStackTrace(); } }
step 4: react
this will be the meat of your program, reacting to the outside world. before you can do that, you need to parse the messages that d.tools sends back. By looking at the address of the message, you can identify the device that is talking to you, and the message contains the value it is reporting.

there is also some basic error messages that can be reported in case a device fails or the message is corrupted. this simple if/else statement will help you parse out those messages.
// if you are listening to everything, here is how to pull the different types of messages back apart: public static class TestListener implements OSCListener { public void acceptMessage(Date time, OSCMessage message) { // message.getAddress() returns the "URL" or path of your component as a String // error messages have the address "/error/...." if(message.getAddress().startsWith(("/error"))) { System.out.println("received a communication error."); } //1 Argument of type String is the address of the component that was added/removed. // connect messages have the address "/connect" else if (message.getAddress().equals("/connect")) { System.out.println("New hardware connected: " +message.getArguments()[0]); } // disconnect messages have the address "/disconnect" else if (message.getAddress().equals("/disconnect")) { System.out.println("Hardware disconnected: " +message.getArguments()[0]); } //for rfids: 1 Argument of type String; //10 characters, each character is a string representation of a hexadecimal number (0..9A..F) else if (message.getAddress().startsWith("/rfid")) { System.out.println("Rfid reader "+message.getAddress()+" saw tag "+message.getArguments()[0]); } //for buttons: 1 Argument of type Integer; 1 means pressed, 0 means released //for switches: 1 Argument of type Integer; 1 means toggled on, 0 means toggled off //for sliders,knobs,analog sensors: 1 Argument of type Integer; 0 is min. value, 255 max value. else { if(message.getArguments()[0] instanceof Integer) { System.out.println("Received message for "+message.getAddress()+ " with value "+message.getArguments()[0]); } } } }
note1: running dtools-lite concurrently with the d.tools eclipse plugin
only one program can take control of a COM port at a time. if you want to write dtools-lite programs in an eclipse environment that also has the installed and loaded, you have to make sure that dtools-eclipse-plugin doesn't lock the com port on startup. in eclipse, go to window->preferences->d.tools preferences and either enter a different COM port or set the hardware communication protocol to UDP packets.


note2: what's up with these OSC messages?
The messages passed between hardware and PC use the OpenSoundControl format (OSC). If you want to find our more about OSC, please look at:
http://www.cnmat.berkeley.edu/OpenSoundControl/


Questions about the website? Contact: hci-webmaster at lists.stanford.edu