Difference between revisions of "Edit Device Template"

From LinuxMCE
Jump to: navigation, search
(→‎Configuration script)
 
(18 intermediate revisions by 9 users not shown)
Line 1: Line 1:
−
<p>This is how you define a Device Template, and specify what data it needs, and what commands and events it will implement.</p>
+
{| align="right"
−
<p>If "Implements DCE" is checked, that means this Device Template will be able to run as a stand-alone device, connecting directly to the DCE Router to receive and process its own data, commands and events.  [[Does the device Implement DCE?]] for an explanation.</p>
+
  | __TOC__
−
<p>Design Objects are menus that appear on the Orbiters, and here is where you specify what design objects, or menus, should be used to control this device.  [[Design Objects]]</p>
+
  |}
−
<p>You also specify here what devices this one will be controlled via, also referred to as what devices are eligible parents.  This is an "or" relationship.  Any device that matches any of the categories or any of the device templates you specify will be considered a valid parent, and the user will be allowed to create a child device based on this device template.  [[Understanding Controlled Via (aka Parent)]]</p>
+
[[Category: Admin Website]]
 +
[[Category: Programmer's Guide]]
 +
[[Image:EditDeviceTemplate.jpg|thumb|250px|Select Device Template Admin Page]]
 +
[[Image:Editdevicetemplatepage.jpg|thumb|250px|Edit Device Template Admin Page]]
 +
This is how you define a Device Template, and specify what data it needs, and what commands and events it will implement.
  
−
<p>Here you can also specify what package will contain this device's software.  If you choose an existing package, then this device will be added to that software package the next time LinuxMCE's "MakeVersion" program is run.  Typically, however, each developer will create his own package to contain his software, and only group multiple Device Templates together into a package if they logically belong together as a whole.  LinuxMCE's "standard plug-in" package is an example.  It contains all the standard plug-in devices since they are really inseparable and belong in the same package.  [[Packages]]</p>
+
The data, commands and event sections pertain to [[LinuxMCE Libraries DCE]].
  
−
<p>If the device is an Audio/Video device, whether or not it implements DCE, you should check the box. This will enable a button allowing you to specify a variety of extra information about this device that is specific to A/V equipment, such as what inputs it uses, if it has different 'modes', settings for controlling it via infrared, etc.</p>
+
===Device Template # ....===
  
−
<p>The data, commands and event sections pertain to [[LinuxMCE Libraries DCE]].</p>
+
====Description====
 +
This will be used as the name of the device template.
  
−
<p>When you specify what <b>data parameters</b> this device needs, try to use one of the existing data parameters in the list if there is an appropriate one.  Which one you choose is unimportant so long as the type is correct (string, integer, etc.).  DCE makes no differentiation between the parameters--they are just names.  If this device implements DCE, then DCEGen will create member variables for setting/accessing all the data parameters for your device, and the names of the members and functions will be the same as the name on the list.  Also, when the user adds an instance of this device to his system, either manually or with the wizard, he will be able to fill in a value for this parameter if you check "Allowed to Modify".  If you check "Required", then some value will be required and the parameter cannot be empty.  If you check "Use Device Template Default", then whatever value you put in here as the default will be used by every device.  Note that if you put in a default value, do not check "Allowed to Modify", then the device will be created with the default value.  However, if you later change the default value, all the devices values will not change unless you check this "Use Device Template Default" box.  In that case, the device really has no local value and just uses the current default every time.  If "Set by Device" is checked, then when the DCE class is generated a "set" methods will also be created so the device can set the value itself.  Otherwise the data parameter is considered 'read-only' by the device and can only be changed using the "LinuxMCE Admin" web site.</p>
+
====Implements DCE====
 +
If "Implements DCE" is checked, that means this Device Template will be able to run as a stand-alone device, connecting directly to the DCE Router to receive and process its own data, commands and events.  [[Does the device Implement DCE?]] for an explanation.
  
−
<p>Because most devices implement lots of <b>commands</b>, and similar devices will always implement similar commands, commands are put into groups and the groups are added to the device template rather than adding the commands manually.  A TV, for example, can have 100 "standard" commands--like Volume Up/Down, Channel Up/Down, On/Off, Brightness Up, etc.  Rather than having to add every command to every TV, a group called "Standard TV commands" can be created, and you just add the group to the TV.  Command Groups use the same categories as the device template themselves.  By default, you will only see here the command groups within the same category as the device template to keep the screen clean.  Just check the command groups you want.  However, there is a pull-down listing every single command group so you can add command groups that are not in the same category.  You can also create a new command group and then specify what commands belong to that group. When you create or edit a command group you will have the option of creating/editing the commands, and there you will be able to specify what parameters that command takes.</p>
+
====Command line====
 +
The name of the binary located in /usr/pluto/bin that the Launch_Manager will try to start in a screen session.
  
−
<p>Whatever <b>events</b> this device will fire are also added here. When you create/edit an event, you can specify what parameters that event takes.</p>
+
====Device Category====
 +
The category to which these devices belong.
  
−
<p>If this device can be controlled via infrared, the infrared code for each command will need to be stored or learned.  The number of different models for A/V equipment is staggering.  However most manufacturers always use the same infrared codes across their whole line.  For example, a Sony remote control for 1 TV will control all other Sony TV's too.  So rather than requiring the user to add infrared codes for every Sony TV, we just create an infrared group "Sony TV Commands".  Then you can add the DCE Command to Infrared Code commands to the group.  Later when someone else adds a Device Template for another model of Sony TV, they can just specify that it uses the same Infrared Group.  Note that the infrared group should therefore be a superset of all the commands--every command for every Sony TV.  Some high-end models may have commands like "Wide screen" vs "Normal", which the low-end models do not support.  In this case, the high-end model may have more commands than the low-end model, but all the commands should be in the infrared group.  The low-end model will never use the infrared codes that it doesn't support, but at least they will be there and different infrared groups will not be required.  When the manufacturer changes the infrared codes their, then a new infrared group will be required.</p>
+
====Manufacturer====
 +
The company that makes these devices.
 +
 
 +
====Manufacturer URL====
 +
Website of aforementioned manufacturer.
 +
 
 +
====Internal URL suffix====
 +
 
 +
 
 +
====Design Objects to use as remotes====
 +
Design Objects are menus that appear on the Orbiters, and here is where you specify what design objects, or menus, should be used to control this device.  [[Design Objects]]
 +
 
 +
====This device is controlled via====
 +
You also specify here what devices this one will be controlled via, also referred to as what devices are eligible parents.  This is an "or" relationship.  Any device that matches any of the categories or any of the device templates you specify will be considered a valid parent, and the user will be allowed to create a child device based on this device template.  [[Understanding Controlled Via (aka Parent)]]
 +
 
 +
====This device is controlled via category====
 +
 
 +
====Packages====
 +
Here you can also specify what package will contain this device's software.  If you choose an existing package, then this device will be added to that software package the next time LinuxMCE's "MakeVersion" program is run.  Typically, however, each developer will create his own package to contain his software, and only group multiple Device Templates together into a package if they logically belong together as a whole.  LinuxMCE's "standard plug-in" package is an example.  It contains all the standard plug-in devices since they are really inseparable and belong in the same package.  [[Packages]]
 +
 
 +
====Audio/Video Device====
 +
If the device is an Audio/Video device, whether or not it implements DCE, you should check the box.  This will enable a button allowing you to specify a variety of extra information about this device that is specific to A/V equipment, such as what inputs it uses, if it has different 'modes', settings for controlling it via infrared, etc.
 +
 
 +
====Is PlugIn====
 +
====Is Embedded====
 +
====Inherits MAC From PC====
 +
====Is IP Based====
 +
====Comm Method====
 +
====Configuration script====
 +
The configuration script is run until it successfully exits. It is run to setup a device initially, like setting up an extension for a new IP phone. It must exist in /usr/pluto/bin.
 +
 
 +
If the device is detected, the script is being called using the following parameters
 +
-d <device-id>   # The device ID for the new device
 +
-i <ip-address>  # The IP address for the new device
 +
-m <mac-address> # The MAC address for the new device
 +
 
 +
If "Device needs reconfiguring" is ticked, Config_Device_Changes.sh runs the script mentioned here. Config_Device_Changes.sh runs on every router reload.
 +
 
 +
====Comments====
 +
 
 +
===Device data===
 +
When you specify what '''data parameters''' this device needs, try to use one of the existing data parameters in the list if there is an appropriate one.  Which one you choose is unimportant so long as the type is correct (string, integer, etc.).  DCE makes no differentiation between the parameters--they are just names.  If this device implements DCE, then DCEGen will create member variables for setting/accessing all the data parameters for your device, and the names of the members and functions will be the same as the name on the list.  Also, when the user adds an instance of this device to his system, either manually or with the wizard, he will be able to fill in a value for this parameter if you check "Allowed to Modify".  If you check "Required", then some value will be required and the parameter cannot be empty.  If you check "Use Device Template Default", then whatever value you put in here as the default will be used by every device.  Note that if you put in a default value, do not check "Allowed to Modify", then the device will be created with the default value.  However, if you later change the default value, all the devices values will not change unless you check this "Use Device Template Default" box.  In that case, the device really has no local value and just uses the current default every time.  If "Set by Device" is checked, then when the DCE class is generated a "set" methods will also be created so the device can set the value itself.  Otherwise the data parameter is considered 'read-only' by the device and can only be changed using the [[LinuxMCE Admin Website]].
 +
 
 +
===Commands===
 +
Because most devices implement lots of '''commands''', and similar devices will always implement similar commands, commands are put into groups and the groups are added to the device template rather than adding the commands manually.  A TV, for example, can have 100 "standard" commands--like Volume Up/Down, Channel Up/Down, On/Off, Brightness Up, etc.  Rather than having to add every basic command to every TV, a group called "Standard TV commands" can be created, and you just add the group to the TV.  Command Groups use the same categories as the device template themselves.  By default, you will only see here the command groups within the same category as the device template to keep the screen clean.  Just check the command groups you want.  However, there is a pull-down listing every single command group so you can add command groups that are not in the same category.  You can also create a new command group and then specify what commands belong to that group.  When you create or edit a command group you will have the option of creating/editing the commands, and there you will be able to specify what parameters that command takes.
 +
 
 +
If this device can be controlled via infrared, the infrared code for each command will need to be stored or learned.  The number of different models for A/V equipment is staggering.  However most manufacturers always use the same infrared codes across their whole line.  For example, a Sony remote control for 1 TV will control all other Sony TV's too.  So rather than requiring the user to add infrared codes for every Sony TV, we just create an infrared group "Sony TV Commands".  Then you can add the DCE Command to Infrared Code commands to the group.  Later when someone else adds a Device Template for another model of Sony TV, they can just specify that it uses the same Infrared Group.  Note that the infrared group should therefore be a superset of all the commands--every command for every Sony TV.  Some high-end models may have commands like "Wide screen" vs "Normal", which the low-end models do not support.  In this case, the high-end model may have more commands than the low-end model, but all the commands should be in the infrared group.  The low-end model will never use the infrared codes that it doesn't support, but at least they will be there and different infrared groups will not be required.  When the manufacturer changes the infrared codes their, then a new infrared group will be required.
 +
 
 +
Places to get the commands for your device:<br/>
 +
[http://www.remotecentral.com Remote Central]<br/>
 +
[http://www.awe-europe.com/ir_232.html Awe Europe]
 +
 
 +
===Events===
 +
Whatever '''events''' this device will fire are also added here.  When you create/edit an event, you can specify what parameters that event takes.
 +
 
 +
 
 +
===Plug & Play===
 +
====Range of MAC====
 +
The MAC range is used to implement Plug and Play as devices appear on the network. However, instead of the regular column separated groups of digits, LinuxMCE uses the decimal value of a MAC address. A script has been provided to aid in the conversion of the MAC address from hexadecimal to decimal. Run the <code>/usr/pluto/bin/convert_mac</code> script on your core, and copy the resulting number to your template. <br>
 +
 
 +
If the mac address for your specific hardware is 00:01:02:03:''04:05'', it is likely that all devices that start with 00:01:02:03 are part of the same product. To find the upper and lower limits of the range, run
 +
:<code>/usr/pluto/bin/convert_mac 00:01:02:03:'''00:00''' </code>
 +
:<code>/usr/pluto/bin/convert_mac 00:01:02:03:'''FF:FF''' </code>
 +
 
 +
{{p}}
 +
 
 +
====Vendor Model ID====
 +
The vendor model ID is the PCI ID of the device in question. vendor_id plus product_id. If the PCI card has subvendor and subproduct id, add those too.
 +
lspci --nn -v
 +
That above command will give you a list of all PCI devices in your system. Choose the one you are interested in, and note the details.
 +
The DVB-S card in this example has these details:
 +
05:05.0 Multimedia controller [0480]: Philips Semiconductors SAA7146 [1131:7146] (rev 01)
 +
        Subsystem: Technotrend Systemtechnik GmbH Device [13c2:1016]
 +
        Flags: bus master, medium devsel, latency 32, IRQ 16
 +
        Memory at f6101000 (32-bit, non-prefetchable) [size=512]
 +
        Kernel driver in use: budget dvb
 +
        Kernel modules: budget, snd-aw2
 +
The relevant data in here are the colon seperated information in line 1 and line 2. These informations have to be glued together, while the colon has to be removed, i.e.
 +
1131714613c21016
 +
is the Vendor Model ID, in this example. If you don't have a subsystem, put the vendor and product id from the first line only.
 +
====PNP protocol====
 +
* DHCP if it is IP based
 +
* Empty for the rest has worked for me.
 +
====Serial Number====
 +
====Parms====
 +
* For PCI based stuff, enter 175|pci
 +
* For USB based stuff, enter 162|
 +
====PNP detection script====
 +
The PNP detection script is defined for RS-232 based devices. It is run, whenever a RS-232 port changes state.
 +
 
 +
====Comment====
 +
Put some nice comments about this specific pnp entry in here, so people can see what's special about it. Especially helpful when adding new MAC ranges to existing templates.
 +
 
 +
===Device Template Related===
 +
====Add device template related #ID====
 +
====Extra====
 +
===Screens===
 +
====This device requires the following screens====

Latest revision as of 14:34, 10 April 2014

Select Device Template Admin Page
Edit Device Template Admin Page

This is how you define a Device Template, and specify what data it needs, and what commands and events it will implement.

The data, commands and event sections pertain to LinuxMCE Libraries DCE.

Device Template # ....

Description

This will be used as the name of the device template.

Implements DCE

If "Implements DCE" is checked, that means this Device Template will be able to run as a stand-alone device, connecting directly to the DCE Router to receive and process its own data, commands and events. Does the device Implement DCE? for an explanation.

Command line

The name of the binary located in /usr/pluto/bin that the Launch_Manager will try to start in a screen session.

Device Category

The category to which these devices belong.

Manufacturer

The company that makes these devices.

Manufacturer URL

Website of aforementioned manufacturer.

Internal URL suffix

Design Objects to use as remotes

Design Objects are menus that appear on the Orbiters, and here is where you specify what design objects, or menus, should be used to control this device. Design Objects

This device is controlled via

You also specify here what devices this one will be controlled via, also referred to as what devices are eligible parents. This is an "or" relationship. Any device that matches any of the categories or any of the device templates you specify will be considered a valid parent, and the user will be allowed to create a child device based on this device template. Understanding Controlled Via (aka Parent)

This device is controlled via category

Packages

Here you can also specify what package will contain this device's software. If you choose an existing package, then this device will be added to that software package the next time LinuxMCE's "MakeVersion" program is run. Typically, however, each developer will create his own package to contain his software, and only group multiple Device Templates together into a package if they logically belong together as a whole. LinuxMCE's "standard plug-in" package is an example. It contains all the standard plug-in devices since they are really inseparable and belong in the same package. Packages

Audio/Video Device

If the device is an Audio/Video device, whether or not it implements DCE, you should check the box. This will enable a button allowing you to specify a variety of extra information about this device that is specific to A/V equipment, such as what inputs it uses, if it has different 'modes', settings for controlling it via infrared, etc.

Is PlugIn

Is Embedded

Inherits MAC From PC

Is IP Based

Comm Method

Configuration script

The configuration script is run until it successfully exits. It is run to setup a device initially, like setting up an extension for a new IP phone. It must exist in /usr/pluto/bin.

If the device is detected, the script is being called using the following parameters 

-d <device-id>   # The device ID for the new device
-i <ip-address>  # The IP address for the new device
-m <mac-address> # The MAC address for the new device

If "Device needs reconfiguring" is ticked, Config_Device_Changes.sh runs the script mentioned here. Config_Device_Changes.sh runs on every router reload.

Comments

Device data

When you specify what data parameters this device needs, try to use one of the existing data parameters in the list if there is an appropriate one. Which one you choose is unimportant so long as the type is correct (string, integer, etc.). DCE makes no differentiation between the parameters--they are just names. If this device implements DCE, then DCEGen will create member variables for setting/accessing all the data parameters for your device, and the names of the members and functions will be the same as the name on the list. Also, when the user adds an instance of this device to his system, either manually or with the wizard, he will be able to fill in a value for this parameter if you check "Allowed to Modify". If you check "Required", then some value will be required and the parameter cannot be empty. If you check "Use Device Template Default", then whatever value you put in here as the default will be used by every device. Note that if you put in a default value, do not check "Allowed to Modify", then the device will be created with the default value. However, if you later change the default value, all the devices values will not change unless you check this "Use Device Template Default" box. In that case, the device really has no local value and just uses the current default every time. If "Set by Device" is checked, then when the DCE class is generated a "set" methods will also be created so the device can set the value itself. Otherwise the data parameter is considered 'read-only' by the device and can only be changed using the LinuxMCE Admin Website.

Commands

Because most devices implement lots of commands, and similar devices will always implement similar commands, commands are put into groups and the groups are added to the device template rather than adding the commands manually. A TV, for example, can have 100 "standard" commands--like Volume Up/Down, Channel Up/Down, On/Off, Brightness Up, etc. Rather than having to add every basic command to every TV, a group called "Standard TV commands" can be created, and you just add the group to the TV. Command Groups use the same categories as the device template themselves. By default, you will only see here the command groups within the same category as the device template to keep the screen clean. Just check the command groups you want. However, there is a pull-down listing every single command group so you can add command groups that are not in the same category. You can also create a new command group and then specify what commands belong to that group. When you create or edit a command group you will have the option of creating/editing the commands, and there you will be able to specify what parameters that command takes.

If this device can be controlled via infrared, the infrared code for each command will need to be stored or learned. The number of different models for A/V equipment is staggering. However most manufacturers always use the same infrared codes across their whole line. For example, a Sony remote control for 1 TV will control all other Sony TV's too. So rather than requiring the user to add infrared codes for every Sony TV, we just create an infrared group "Sony TV Commands". Then you can add the DCE Command to Infrared Code commands to the group. Later when someone else adds a Device Template for another model of Sony TV, they can just specify that it uses the same Infrared Group. Note that the infrared group should therefore be a superset of all the commands--every command for every Sony TV. Some high-end models may have commands like "Wide screen" vs "Normal", which the low-end models do not support. In this case, the high-end model may have more commands than the low-end model, but all the commands should be in the infrared group. The low-end model will never use the infrared codes that it doesn't support, but at least they will be there and different infrared groups will not be required. When the manufacturer changes the infrared codes their, then a new infrared group will be required.

Places to get the commands for your device:
Remote Central
Awe Europe

Events

Whatever events this device will fire are also added here. When you create/edit an event, you can specify what parameters that event takes.


Plug & Play

Range of MAC

The MAC range is used to implement Plug and Play as devices appear on the network. However, instead of the regular column separated groups of digits, LinuxMCE uses the decimal value of a MAC address. A script has been provided to aid in the conversion of the MAC address from hexadecimal to decimal. Run the /usr/pluto/bin/convert_mac script on your core, and copy the resulting number to your template.

If the mac address for your specific hardware is 00:01:02:03:04:05, it is likely that all devices that start with 00:01:02:03 are part of the same product. To find the upper and lower limits of the range, run

/usr/pluto/bin/convert_mac 00:01:02:03:00:00
/usr/pluto/bin/convert_mac 00:01:02:03:FF:FF



Vendor Model ID

The vendor model ID is the PCI ID of the device in question. vendor_id plus product_id. If the PCI card has subvendor and subproduct id, add those too. 

lspci --nn -v

That above command will give you a list of all PCI devices in your system. Choose the one you are interested in, and note the details. The DVB-S card in this example has these details: 

05:05.0 Multimedia controller [0480]: Philips Semiconductors SAA7146 [1131:7146] (rev 01)
        Subsystem: Technotrend Systemtechnik GmbH Device [13c2:1016]
        Flags: bus master, medium devsel, latency 32, IRQ 16
        Memory at f6101000 (32-bit, non-prefetchable) [size=512]
        Kernel driver in use: budget dvb
        Kernel modules: budget, snd-aw2

The relevant data in here are the colon seperated information in line 1 and line 2. These informations have to be glued together, while the colon has to be removed, i.e. 

1131714613c21016

is the Vendor Model ID, in this example. If you don't have a subsystem, put the vendor and product id from the first line only.

PNP protocol

  • DHCP if it is IP based
  • Empty for the rest has worked for me.

Serial Number

Parms

  • For PCI based stuff, enter 175|pci
  • For USB based stuff, enter 162|

PNP detection script

The PNP detection script is defined for RS-232 based devices. It is run, whenever a RS-232 port changes state.

Comment

Put some nice comments about this specific pnp entry in here, so people can see what's special about it. Especially helpful when adding new MAC ranges to existing templates.

Device Template Related

Add device template related #ID

Extra

Screens

This device requires the following screens

Retrieved from "http://wiki.linuxmce.org/index.php?title=Edit_Device_Template&oldid=34915"