Revision as of 16:36, 1 November 2012

Device Template Admin Page

Warning

Most users will never need to use the "Device Template" page unless they want to do development and make their own devices. If you do want to poke around in the Device Templates, be careful not to change anything unless you know what you are doing. Since changing something here could cause your device to not function properly, it is strongly advised that you track ALL the changes you make so that you can revert them to their original state. All the settings for your device which you may want to change can be set using the Wizard, which is safer.

What's a template?

A device template is a definition of everything necessary for a device to operate within a LinuxMCE system. It is a container for all the information that LinuxMCE needs to know about a device. All the data in a template is stored in the database, and queried as needed throughout the system.

In LinuxMCE, a template defines what the device is called, how it relates to other devices in the house, where it should be created on the device tree (its parent), how to find the device (the plug and play information), what software package is needed to be installed for it to work, or what software package contains the software needed to use it, how to install it, what commands it supports, what events it can emit, how it should interact with messenger, etc.

Why templates?

These software modules are called templates because they serve as patterns used to add devices. When a new device is added to the system, it is created as an instance of the parent template that defines it, which makes it inherit the data in the template. While some of this is shared between all device instances and can not be changed, the per device data populated in the new device from the template can be edited at will after creation.
A simple way to understand the concept is by looking at a template as a blueprint, and a device as a building made from that blueprint.

For example, there will only be one Device Template for the "Sony XYZ-123" Television. You, and several other users may have this TV, and each of you will have your own "Device" that you have named, which may have some settings of its own. Everyone can install the "Sony XYZ-123" from the same template, because it is available. The system will detect it, and ask you if you would like to install it in your home. There is only one "Device Template" for that type of device, but there will be as many devices as users have installed. You can install multiple devices of the same kind using the one template that has been developed for it.
If a template is not available, then it will need to be created, since it is the only way to add a device to LinuxMCE and enable it to use the DCERouter to communicate with the rest of the system.

A "Device Template" is what defines a device, 
and a "Device" is the particular instance installed in the home.  

The availability of templates makes device addition easy.
Since all devices are created from templates, every device is merely an instance of a template. Templates provide a simple method for instantiating devices for DCERouter to interact with.
Because all necessary information has been included in the template, the system knows all the particulars necessary to make that kind of device function within the system. This provides the background for the plug and play capability of LinuxMCE.

The DCERouter, which lies at the core of LinuxMCE's operation, is nothing else than a message router. DCERouter makes routing decisions based on information stored in the database about the devices in the LinuxMCE system. At its heart, it is a messaging bus that sends DCE messages around. The DCE messages are created or interpreted based on the protocol used by each device, enabling various technologies to interact.
The device template ties the messaging bus to a device and any configurations necessary to make it function, including software. Anything can control anything through DCE because everything is translated to DCE by means of a template. Without templates, each piece of hardware would have to have embedded support for DCE, but, with templates, any hardware or software can be added to the system.

Why templates? For DCE interactions.

What are templates used for?

A device template shows the system how to interface with a device. It is used to:

• standardize communication with each particular type of device
• ease device installation and provide Plug And Play capability
• translate various protocols to DCE

Device standardization

A template defines all drivers the device must be bound to, wrappers, package dependencies, and other software necessary for its operation. All software requirements are handled by the template, including creating our common command emulation, or device specific translation. Once all the software and settings have been tied together in a template, any device of the type it was designed to handle can communicate with the system using the same definition. A template standardizes the way a particular type of device interacts within the system.

Device installation and PnP

Templates hold the unique device information. When it detects the device, it ties to the needed particulars, and translates commands from input device to DCE, which communicates with everything. Because of the existence of templates, LinuxMCE can identify a device, know which packages to grab, and, know which scripts or database queries to run to set it up.

Protocol translation

When DCERouter receives events and commands, it uses the device template instance to interpret, then deliver them to the appropriate recipient.

Using device templates

The point of the device template structure is that you should not typically need to add them, as they are installed when the appropriate device makes an appearance to the system. It is possible to add them manually, but if you have to, something typically went wrong. In LinuxMCE, device addition is supposed to be Plug And Play. However, you may have a need to create a template for a device not recognized by the system.
This can happen when:

• the device's MAC address is not in the range that is currently set for the device. Unfortunately, manufacturers are not required to publish the range of identifiers they assign to each device model they produce, and finding them is not straight forward. If you happen to have a device that you know to be compatible with LinuxMCE but does not get detected, you can add the range of your specific device to the template. You will find instructions that will help you accomplish that in the Plug & Play section of the Edit Device Template page.
• the device ID is not in the expected range as described above for the MAC address.
• there are more than one of the same model of device, and the "only one per md" setting is set.
• the radars are not running, or are not running correctly. A radar in LinuxMCE is a process that scans for available resources. Currently, only hard drives and network shares are scanned, in addition to serial device detection scripts. You can see what radars are available by running the command ls /usr/pluto/bin/*Radar*.sh
  See ssh from windows for instructions on using the command prompt.
• the device is compatible with LinuxMCE, but no template has been created for it yet.

Note

The system runs these radars, they should not generally be run manually, as some are backgrounded scripts which would just create multiple instances.

• the device is not compatible with LinuxMCE, so no template has been created, nor can be created. the device will not work with LinuxMCE and needs to be replaced with a LinuxMCE compatible device.
• unrelated things, like USB just not working under the strain of poll, which should not happen, or any other hardware error.

Note

once committed by someone with credentials, a template can not be deleted from the system.

Template development

Sometimes, you may need to edit a template to add a MAC address or identifier. This is a matter of adding the values. In the event you need to create a template, it is usually very helpful to look at one that performs a function similar to that of the device you are adding, copy the settings, and edit the fields by making some educated guesses, or exploring through trial and error by using a process of elimination. Please beware that changing setting in templates may make the corresponding devices inoperable. Always make note of what you are changing, and why, and keep track of the changes you make in order to be able to revert them in case you break something. A short ink mark lasts longer than a long memory.

Device templates are not all mythical beasts with 9 heads. Adding a remote control is pretty easy if you know our codes (which you can explore by looking at the template for another remote) and you can use xev. For instance, all that is necessary for an IR remote, is to adjust the mapping to correspond with the code emitted when pushing the buttons. Many things, like adding a capture card, are harder, and template development for some devices is an advanced topic that requires too many skills to be covered in this documentation. Some do require and expert level knowledge of the device to add, how it communicates, the protocols it uses, the Linux software it uses, the ability to write drivers, etc. That is not to say that you can not work with templates at all. If you are willing to do the research, have some time to experiment with the various settings, and feel you have the skills to do so, please help us expand our set of templates. If you are just dealing with a basic device, and just need to make adjustments, please read on.

Making Changes to Templates

If you make changes to the Device Template, this will affect your local system only. However, if you have fixed some errors, added functionality to an existing Device Template or created your own Device Template, you can use sqlCVS to submit a template for approval to fold those changes back into the master database so everyone can benefit from them. The same is true with everything in your local database--the user interface, even the online documentation you are reading now is editable. When you check-in changes using sqlCVS, sqlCVS will isolate those changes and notify the developer who is responsible for quality assurance for that section. Once the developer has confirmed the changes, he can have the changes merged back into LinuxMCE's main development database, which will eventually get propagated to the testing and release databases if the changes pass the tests.

Merging Template Changes

We recommend that you do merge any changes you make locally to the Device Templates because if you do not, then sqlCVS will not update that Device Template with any changes that may have been made to the master database. Your local copy will then likely become out of date. Note that sqlCVS will notify you when it does an update if you have changed a Device Template that was also changed in the master database. You will have the option of over-writing your local Device Template with the master one, or keeping your modified local copy.

Using Device Template Page

• Select the manufacturer and the device category and click "Apply filter" to restrict the device templates list to those from the device category and manufacturer selected.
• Click "Autofilter" to make this operation to be performed automatically every time the device category or manufacturer is changed.
• If you know the device template number, just type it in "device template" box.

Creating a New Template

• How do I create/edit my own Device Template
• Tell me about DCE (Data, Commands & Events)