Phidget Dictionary
General Overview
The Phidget Dictionary is a central key-value pair database for networked programs. It is a server provided by the Phidget Network Server. It allows you to store program data centrally - in the form of key-value pairs - on the same server as your Phidgets.
A Dictionary is like any other Phidget software object: You create and open it (though you don't have to wait for attachment or attach it in any way). You can subscribe to data change events, and get updates on these events from multiple devices. And when you're done, you simply close and delete it. Just like any other Phidget software object over the network, you run the functional code on your client, and the server simply runs the Phidget Network Server, which includes the Phidget Dictionary.
Since the Dictionary is a popular feature on our Phidget Single Board Computer (SBC), we will use that as an example. Here's a diagram of what it might look like:
In this example, the Phidget SBC is hosting a Phidget Server and a Dictionary Server. The Phidget Server allows other computers on the network to access and control the ports on the Phidget SBC. You can learn more about using Phidgets over the network on the Phidget Network Server page. The dictionary contains key-value pairs which can be added, removed and updated by the Phidget SBC hosting the dictionary or any other computer on the network.
Of course, you can handle data storage and sharing internally within your program, but the Phidget Dictionary is simple to use and setting up event handlers to notify your programs of changes in the dictionary can also be useful. For a complete list of dictionary functions, see the Phidget22 API and select Phidget Dictionary from the drop-down menu.
The dictionary becomes more valuable the more clients you have interacting with your Phidgets system. The intended use for the dictionary is as a central repository for communication and persistent storage of data between several client applications. For example, it can be used as a higher level interface exposed by one application that controls the Phidgets for others to access, rather than every client talking directly to the Phidgets themselves.
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.
