Difference between revisions of "Make a DCE Device in 5 minutes"

Revision as of 15:32, 11 August 2007

There are 2 ways to add a new device. 1) For most external devices that are controlled by RS232, USB or Ethernet, you can use GSD (Generic Serial Device). There is a 'fill-in-the-blanks' web form for you to specify the protocol--no programming is required. GSD also includes an embedded Ruby-language processor, so you can do almost anything and even complex, sophisticated devices can be created easily. Whatever protocol and Ruby commands you input are automatically sent back to our master database and shared with all other LinuxMCE users, so everyone can use the device (you can turn this option off). Nearly all external devices, like home automation components, use GSD. 2) We also have a generator that will build you a cross-platform C++ project. LinuxMCE's sophisticated, internal devices like Bluetooth communication, software media players, etc. are all written in C/C++.

Either way, the first step is to define the data, commands and events for your device. Go to the LinuxMCE Admin Website that was installed on your computer when you installed LinuxMCE. Login, and choose "Advanced", "Device Templates".

First see if you can find an existing device that has a similar function to the one you want to create. Choose an existing manufacturer and/or category to see some the devices in the "Models" list. Click edit to view the device's data, command and events. Note that the command are put into 'groups', so you will need to click on the command group to see the commands that device implements. Now figure out what data, commands and events your device will use. You can also click on "Advanced", "DCE", and view a list of all the commands in the system and which devices implement them.

The data parameters is not really important. It can be anything your device will need to run. If the device is going to control some equipment via RS232, you'll want a parameter to indicate the COM port, for example.

Next, figure out what command your device will want to implement. Here it's more important to try to use the same commands in the same way as other, similar devices. This will mean that the remote controls (Orbiters) for those devices will work for yours too. Also, other developers may expect your device to implement a logical command. For example, someone may develop a doorbell device, which allows the user to pause all his media when someone is at the door so he will hear the bell. The doorbell device may, therefore, send a "Pause" command destined to every device in the house of the category "Media Player", expecting that any media player should know what that means. From the Device Template list page there is also a link to manage commands which lets you see all the existing commands, what parameters they take, what devices implement them, and how, so that you can be sure your device is capable of behaving in a similar manner. Of course, you can add as much custom functionality as you want, but it's recommended that your device implements at least the basics in a consistent manner. On/Off, skip forward, skip back, etc.

Lastly, decide on what events your device should fire. Again, try to use the same events in the same way as similar devices. The user may have created an event handler, for example, that turns on a siren when the "Security Breach" event is detected. If you are making a device for an alarm panel and see that the other panels fire the "Security Breach" event, then if yours fires the same event the user will be swap his current panel for yours and know that all his event handlers will still work.

Once you decided on the data, command and events, you've done the hard part. Now just go back to the List Page page, choose the manufacturer, or add one, and choose a category. Once those are chosen, the 'add new' box is available under the Models list. Type in a descriptive name for your device, and click 'add'.

You are now on the Edit Page page. Check that the device implements DCE. You can leave alone the remotes, controlled via, package and a/v sections for now.

Add your device's data parameters. You can use an existing parameter if it's applicable, or add one. The name is really just a description.

You will see here all the Command Groups that other devices in this category already implement. Click 'Edit Commands' to see what commands are in that group. If there is a group that is appropriate for your device, just enable it to add those commands to your device. You can also create one more new groups. All commands in all groups you select will be implemented by your device. Then add the commands to your device, explaining how your device implements them. You can also add new commands. When adding the parameters for your commands, you can make the parameters "out" parameters. This means when another device sends you the command, you will get a pointer to this parameter--rather than the parameter itself. You just assign the value you want to return, and the other device that sent you the command will see it.

Lastly, add the events, and click save.

Now, decide how you want to implement your device. Choose one of the following: GSD.