Phidget Dictionary

General Overview

Dictionary is Phidget channel class that exports a key-value pair database. Dictionaries are create and made accessible by the Phidget Network Server. A Dictionary channel is created and opened like any other Phidget channel. Matching is done using either the serial number or the label assigned to the dictionary.

The backing pseudo-device that exports the Dictionary device channel is maintained by the Phidget Network Server, and is created when the server starts. When the server exits, the pseudo-device is deleted, and any changes to dictionaries are lost.

The basic functionality of a Dictionary is to maintain configuration information in a central location. Multiple clients can attach to the same dictionary, and set handlers for add, update and delete events, making the dictionary useful for monitoring and communicating state.

Using The Dictionary

To use the Dictionary, you would create a Dictionary object within your code, just like you would any other Phidget software object. To "listen" to changes of the value associated with a key, the Dictionary has a onAdd(), onRemove(), and onUpdate() event functions (exact name dependant on programming language used). You can write code in these event handlers to react differently depending on which pair is being changed.

Go into the Phidget Control Panel and click on the 'Network Server tab and ensure the server is started.

Here's an example of how you might use the dictionary in a C program:

// Declare the dictionary handle
PhidgetDictionaryHandle dict;

// Create the new dictionary object using the handle
PhidgetDictionary_create(&dict);
PhidgetDictionary_addDictionary(5000,"myDictionary"); //set a serial number and label for the dictionary

// Open connection to the dictionary using the serial number
Phidget_setDeviceSerialNumber(dict, 5000);
Phidget_open(dict);

// Add a key-value pair to the dictionary
char *key1 = "001";
char *val1 = "first";
PhidgetDictionary_add(dict,key1,val1); 

// Access and print a value from the dictionary based on a given key
char newValue[20];
PhidgetDictionary_get(dict, key1, &newValue,20); // '20' refers to the length of the buffer used to store the result
printf("Value: %s",newValue);

// Remove a pair from the dictionary based on a given key
PhidgetDictionary_remove(dict, key1);

// Close and clean up the dictionary object
Phidget_close(dict);
PhidgetDictionary_delete(&dict);

Have a look at the Phidget22 API documentation to learn how to use these methods in the language of your choice. Select your preferred language from the first drop-down box, and select Dictionary API from the second box.

When you create a dictionary in your code, the Phidget Control Panel will also be able to see it if you have remote Phidgets enabled in the options. Here's what it will look like:

On the left, you can see that dictionaries appear just like attached and remote Phidget devices do. On the right, you can see the contents of the dictionary after double-clicking on it. You can add and remove tags from here as well.

Interestingly, you don't even need a Phidget to use the Dictionary! You can use our libraries and the Phidget Network Server without any Phidgets. Usually, there's not much to broadcast on the Network Server without a Phidget, but the Dictionary is the exception. With it, you'll have access to centralized key-value pair database management, pre-written, that can work across many computers on a local network.