LinuxMCE - User contributions [en]

Implementing Clipsal Interface using Generic Serial Device

2007-06-20T08:01:42Z

Tamjid: /* Explanation */

Clipsal Switches are used for controlling lights, curtains and temperature controls. They can be connected to the Serial Port and can be controlled via a PC. In the following tutorial, we will add Clipsal Switches using Generic Serial Device and implement Lights and Shutter control through the Linux MCE.

== Steps to Add Clipsal Interface ==

* Create a Device Template 'Clipsal Interface' in Device Category: "Interfaces - Lighting Interface #81"
* Check Implements DCE - Command Line - Generic Serial Device
* In the packages, add "Pluto Generic Serial Device"
* In Device Data, add "#37 COM Port on PC(string)"
* In Commands Section, create and select "Ruby Internal Commands"

This Clipsal Interface will act as a parent device to all the child devices (eg. Lights, Curtains) that are controlled via the serial port to which Clipsal Switch is connected. Now create a device from the device template Clipsal Interface.

== Ruby Commands for Lighting ==

The Clipsal Interface will have all the lighting and curtains as its child devices. The commands from child devices will be directed to Clipsal Interface and this interface will send these commands to the serial port to which clipsal switch is connected.

For the Clipsal Interface, following ruby commands will be implemented:

* #Private Method Listing #373
* #Process IDLE #351
* #Process Incoming Data #350
* #Process Initialize #355
* #Process Receive Command For Child #384
* #Process Release #356

The most important of this command is #Process Receive Command For Child #384, which is process incoming data from child devices. When we receive any command from child device such as Light or Shutter, the ruby commands in this section are invoked and we need to send relevant commands to the serial port to carry out the action on lights or shutters.

To edit the Ruby Commands for #384 Process Receive Command For Child, Edit the Clipsal Interface and click on 'Edit Ruby Codes' besides Implements DCE on the top.

== Ruby Code ==

group_no = device_.childdevices_[cmd.devidto_].devdata_[12]

if cmd.id_ == 192
serial_on = "\\05380079"+group_no+"\r"
log( "Sending " + serial_on + " \n" )
sendCmd(serial_on)
end

if cmd.id_ == 193
serial_off = "\\05380001"+group_no+"\r"
log( "Sending " + serial_off + " \n" )
sendCmd(serial_off)
end

log("We got cmd : " + cmd.id.to_s)

if cmd.id_ == 184
dim_level = cmd.params_[76]
serial_dim = "\\05380002"+group_no+""+dim_level+"\r"
log( "Sending " + serial_dim + " \n")
sendCmd(serial_dim)
end

== Explanation ==

In the ruby code, what is happening is when we receive a command from any of the child devices (such as lights, curtains), we also get its port number. Then, using that port number we make a binary string to be sent to the serial port. That binary string is sent to the serial port defined in the Clipsal Interface Device Data.

eg. Command # 192 is the command to switch light ON. The binary string to switch a light ON to be sent to the serial port is:

\05380079 + Port Number + \r

So, we receive the port number from child device (group_no), concatenate it in the binary string and send it to the serial port defined in the Clipsal Interface.

Implementing Clipsal Interface using Generic Serial Device

2007-06-20T08:01:00Z

Tamjid: /* Ruby Code */

Implementing Clipsal Interface using Generic Serial Device

2007-06-20T07:58:12Z

Tamjid: /* Steps to Add Clipsal Interface */

Here is a detailed example of how to add Clipsal Interface using Generic Serial Device.

2007-06-17T12:49:46Z

Tamjid: Here is a detailed example of how to add Clipsal Interface using Generic Serial Device. moved to Implementing Clipsal Interface using Generic Serial Device

#redirect [[Implementing Clipsal Interface using Generic Serial Device]]

Implementing Clipsal Interface using Generic Serial Device

2007-06-17T12:49:46Z

Tamjid: Here is a detailed example of how to add Clipsal Interface using Generic Serial Device. moved to Implementing Clipsal Interface using Generic Serial Device

Implementing Clipsal Interface using Generic Serial Device

2007-06-17T12:49:12Z

Tamjid:

Generic Serial Device

2007-06-17T12:38:33Z

Tamjid: /* Short example */

[[Category:GSD]]
[[Category:LinuxMCE_Devices]]
Generic_Serial_Device (also knowk as '''GSD''') is a LinuxMCE device that allows end-user to do simple programming for RS232, serial USB or network connected devices.
:Note : The information is not quite complete because I'm not the original author.

== Short description ==
It's a standard DCE device, it only can execute commands and send events .
The main idea is instead of programming a device in C++, compile, link with proper libraries you can edit (in a webpage) few lines of code in ruby which will be executed when device receives that command. It exports several objects into ruby so you'll have access to devicedata, device hierarchy, established connection and so on.

The ruby code for each device template is stored somewhere in ''InfraredGroup_Command'' table. To edit the code go to Wizard> Devices > Generic_Serial_Devices on [[LinuxMCE-admin]] website. You have to add a device from a device template in order to see anything in that page.

Select the device, and click "RubyCodes" button to be able to edit code that will be executed.
You should be able to see commands that are specified in device template (like ON/OFF/WhateverElse) and a group of ''Internal Commands'' which are used to perform certain actions are to add helper functions.

If the command you are trying to add doesn't show on first page, go to ''Add/Remove commands'' and add more commands for your device.

=== Ruby source code ===

There are 2 forms of ruby code you can write :
* standard ruby code (check [http://www.ruby-lang.org/en/] and [http://poignantguide.net/ruby/] for syntax, references and programming guides)
* short form for '''conn_.Send'''
<$"PWON\r"$>
:which simply will send the string ''"PWON\r"'' to device.

You'll have to quick reload router to get new code. Restarting GSD only will keep old code because the code is supplied by [[Infrared_Plugin]] which caches pluto_main and won't update it's cache without full restart of [[DCERouter]]. With this code it creates a ruby source which will be interpreted by embedded ruby.

It will create methods called "cmd_CmdIDx" for each command(x) defined in web interface except ''Private_Method_Listing'' which will be inserted in the body of the class directly without wrapping.

The source usually looks like (''DevID'' is iPK_Device of specific device, ''CmdIDx'' is iPK_Command ) :

require 'Ruby_Generic_Serial_Device'
class Command < Ruby_Generic_Serial_Device::RubyCommandWrapper
end
class Device_DevID < Ruby_Generic_Serial_Device::RubySerialWrapper
def cmd_CmdID1(paramlist)
@returnParamArray.clear
### WEB CODE for CmdID1 GOES HERE ###
return @returnParamArray
end
def cmd_CmdID2(paramlist)
@returnParamArray.clear
### WEB CODE for CmdID2 GOES HERE ###
return @returnParamArray
end
...
def cmd_ReceiveCommandForChild(cmd)
### Process_Receive Command_For_Child GOES HERE ###
end
...
### Private_Method_Listing GOES HERE ###
...
def initialize()
super
@returnParamArray=Array.new
end
### Generated Setters/Getters goes here (may be empty, but usually looks like below) ###
def data_set(value)
@returnParamArray[19]=value
end

end

There might be more then one class definition in that source. This may happen when child device is itself a GSD device.

=== Command details ===
When the command from DCE arrives it is routed to specific device and ''cmd_XXX'' is run. The commands are run one by one, meaning that you cannot run 2 commands simultaneously. This limitation is implied by embedded ruby interpretor which fails if run from multiple threads.
DCE commands may have return parameters (well known GetVideoFrame), as ruby can return only 1 parameter the ''@returnParamArray'' was added. You can see that in each method we insert '''@returnParamArray.clear''' then the real code and then '''return @returnParamArray'''. Also some setters are generated (like the one from above) for code readability.

Beside usual DCE command you'll see some ''Internal Commands''. Here goes a small list and what they do:
* '''Private Method Listing''' - used to insert all kind of helpers
* '''Process IDLE''' - method executed once in a while (may be used to keep connection alive, scan for new devices on serial bus)
* '''Process Incoming Data''' - called when some data is available
* '''Process Receive Command For Child''' - called if the device has children and those are pretty dummy (like Lights under CM11), so practically the parent will do the job. As a parameter you have ''cmd'' which is a wrapper for DCEMessage, so you'll have access to deviceId, senderId, commandID and so on.
* '''Process Initialize''' - called when device is starting (to perform handshake with device or some other initialisation required by protocol)
* '''Process Release''' - to close gracefully connection with device (say "good bye" or something)

== Implementation notes ==
There are several classes that actually need to be touched. Most of the other classes are just for wrapping DCE objects (like Device, Message, Connection and so on) and exporting them into ruby.

Most important classes :
* '''RubyDCEDeviceNode''' is actually the Device, responsable with initialisation and partially a message handler.
* '''RubyDCEEmbededClass''' is bridge between DeviceNode and ruby, it has ''CallCmdHandler'' which does the real call to ruby and sends back result.
* '''RubyIOManager''' is the one responsible for instantiating RubyDCEDeviceNodes, code retrieval, command handler and serializing ruby calls.
* '''RubyDCECodeSupplier''' gives you the ruby code
* '''RubyCommandWrapper''' a wrapper for Message
* '''GSDMessageProcessing''' is [[Message_Translation|message translator]] which will try to run command if it's implemented without translation.
* '''RubySerialIOConnectionWrapper''' helps to wrap Serial and TCP/IP based connection under same interface, see down the hierarchy the connection you need.

There are also some files needed for building a library for ruby with SWIG, let them alone, it should work.

The compilation will give you '''Generic_Serial_Device''' and '''Ruby_Generic_Serial_Device.so''', first file is the binary itself, second file is the bridge library and it will be included by ruby (the request for it is in the first line of the generated source)

== Known issues ==

* Only '''ONE''' command can be executed at a time. This is a limitation of embedded ruby, which should be run from one thread only.
* If command expected an answer, it would wait about 20 seconds for the ruby command to complete, and if the command haven't completed yet, it would send an empty response.
* Most of the data are pretty cryptic (like ''device_.devdata_[114]''), you have to look that that number represents (device data id, command id, command parameter id, event id, event parameter id, some other id)

== Short example ==
For more details about exported classes and available methods check [[GSD_Ruby_Interface]]

Here is a short example from ''Panasonic IP Camera'':
0:require 'Ruby_Generic_Serial_Device'
1:class Command < Ruby_Generic_Serial_Device::RubyCommandWrapper
2:end
3:class Device_47 < Ruby_Generic_Serial_Device::RubySerialWrapper
4:#### 84 ####################################################################
5:def cmd_84(data, format, disable_aspect_lock, streamid, width, height)
6:@returnParamArray.clear
7:conn_.Reconnect()
8:auth_s=device_.devdata_[114]+":"+device_.devdata_[115]
9:auth_a=Array.new;
10:auth_s.each{|c| auth_a.push(c)}
11:
12:fix_path=device_.devdata_[2];
13:fix_path='/'+fix_path if(fix_path[0]!='/'[0]);
14:
15:s = "GET "+fix_path+" HTTP/1.0\r\n"
16:s+= "Accept: */*\r\n"
17:s+= "Authorization: Basic "+auth_a.pack("m").chop+"\r\n"
18:s+= "\r\n"
19:
20:conn_.Send(s)
21:recv=""
22:while(true)
23: buff=conn_.Recv(16384, 5000)
24: if(buff.length() == 0)
25: break
26: end
27: recv = recv + buff
28:end
29:if (recv=~ /^HTTP[^\r\n]+200\sOK.+?\r\n\r\n(.+)$/m)
30: data_set($1)
31: format_set('jpg')
32:end
33:return @returnParamArray
34:end
...
194:#### START SETTERS ####################################################################
195:def initialize()
196:super
197:@returnParamArray=Array.new
198:end
199:def data_set(value)
200:@returnParamArray[19]=value
201:end
202:def format_set(value)
203:@returnParamArray[20]=value
204:end
205:#### END SETTERS ####################################################################
206:end
You can see how command 84 (GetVideoFrame) is implemented:
* it has 6 parameters ''cmd_84(data, format, disable_aspect_lock, streamid, width, height)'', parameters ''data'' and ''format'' are also output parameters
* to set output parameters methods like ''data_set'' and ''format_set'' are automatically generated
* ''device_.devdata_[114]'', ''device_.devdata_[115]'' are the username and password to login into camera
* then it creates HTTP header with basic authorization
* ''device_.devdata_[2]'' is the path to the snapshot (it is configurable because it can change between models)
* it sends the request and waits for the answer
* reads the answer, regexp parse it and gets JPEG content
* sets output parameters
* returns @returnParamArray (the return statement is added automatically)

== Example - Adding Clipsal Interface ==

We can control lights, curtains and climate controls using Clipsal Interface that connects through Serial Port.

[[Here is a detailed example of how to add Clipsal Interface using Generic Serial Device.|Adding Clipsal Interface using Generic Serial Device]]

DCE Binary Communication Protocol

2007-06-04T15:02:32Z

Tamjid: /* How to create a command connection */

== Introduction ==

A device can create a command connection and one or more event connections to the router.

* The command connection is used as an incoming connection and device will use it to receive message from the router (commands).
* An event connection is used by the device as an outgoing connection to notify the router about events or the deliver commands to other devices.

The DCERouter process is listening on 3450 port.

== How to create an event connection ==

Here is how the handshake is made for an event connection:

>> Device sends:

'''''EVENT <my_device_id> '\n''''''

<< To router will respond with :

'''''OK <my_device_id> IP=<device_ip_address> '\n''''''

>> To send a message, the device will send :

'''''MESSAGE <size_of_binary_message> '\n''''''

and then

'''''<serialized_binary_message>'''''

== How to create a command connection ==

Here is how the handshake is made for a command connection:

>> Device sends:

'''''COMMAND <my_device_id> '\n''''''

<< To router will respond with :

'''''OK <my_device_id> IP=<device_ip_address> '\n''''''

>> The device will wait for messages from dcerouter; the router will send :

'''''MESSAGE <size_of_binary_message> '\n''''''

and then

'''''<serialized_binary_message>'''''

== How to serialize data ==

DCE uses SerializeClass to serialize/deserialize data.

The sources can be found here : src/SerializeClass/Serialize.h/cpp.

The deserialize the data, the deserializing module must know the way the data was serialized like this:

- 4 bytes, unsigned long

- 1 byte, unsigned char

Primitives:

- 8 bytes, unsigned int64

- 8 bytes, int64

- 4 bytes, unsigned long

- 4 bytes, unsigned short

- 1 byte, unsigned char

- 1 byte, char

- 1 byte, long

- 4 bytes, float

- 8 bytes, double

- 2 bytes, short

Complex types:

1. string

- STR_LENGTH bytes, the array with chars

- 1 byte, '/0' (value 0x00)

2. block of data

- BLOCK_LENGTH bytes, the array with bytes

3. vector of strings

- VECT_LENGTH bytes, the number of strings from vector

- string 0

- string 1

...

- string VECT_LENGTH - 1

Other complex types serialized (see SerializeClass.cpp for details) :

- map<int,string>

- map<u_int64_t,string>

- map<int,int>

- map<string,string>

- vector<int>

- vector< pair<int,int> >

- map<string, pair<int,int> >

SerializeClass also allowed you to serialize/deserialize custom objects. Examples:

- PlutoColor

- PlutoPoint

- PlutoSize

- PlutoRectangle

- PlutoDataBlock

== How to serialize a message ==

The class used by DCE is Message class from src/DCE/Message.h/cpp unit.

This is how the raw data looks like into a binary message:

- long, value must be 1234 (magic number)

- long, <device_from_id>

- long, <device_to_id>

- long, <device_group_to_id>

- long, <message_id>

- long, <message_priority>

- long, <message_type>

- long, <device_category_to>

- long, <device_template_to>

- unsigned char, <include_children>

- long, <message_broadcast_level>

- long, <message_retry>

- unsigned char, <relative_to_sender>

- long, <expected_response>

- string, <device_list_to>

- unsigned long, <number_of_string_parameters>

* foreach <string_parameter>

* - long, <string_parameter_id>

* - string, <string_parameter_value>

* end_foreach

- unsigned long, <number_of_data_parameters>

* foreach <data_parameter>

* - long, <data_parameter_id>

* - unsigned long, <data_parameter_length>

* - array of bytes, <data_parameter_value>

* end_foreach

- unsigned long, <number_of_extra_messages>

* foreach <extra_message>

* - unsigned long, <serialized_extra_message_length>

* - array of bytes, <serialized_extra_message_value>

* end_foreach

- unsigned long, must be 6789

Enums:

- enum eBroadcastLevel { BL_None=0, BL_DirectSiblings=1, BL_SameComputer=2, BL_SameRoom=3, BL_SameHouse=4, BL_AllHouses=5 };

- enum eRetry { MR_None=0, MR_Retry=1, MR_Persist=2 };

- enum eExpectedResponse { ER_None=0, ER_ReplyMessage, ER_ReplyString, ER_DeliveryConfirmation };

- message types: enum { MESSAGETYPE_COMMAND=1, MESSAGETYPE_EVENT=2, MESSAGETYPE_DATAPARM_CHANGE=3, MESSAGETYPE_REPLY=4,
MESSAGETYPE_DATAPARM_REQUEST=5, MESSAGETYPE_LOG=6, MESSAGETYPE_SYSCOMMAND=7,
MESSAGETYPE_REGISTER_INTERCEPTOR=8, MESSAGETYPE_MESSAGE_INTERCEPTED=9, MESSAGETYPE_EXEC_COMMAND_GROUP=10,
MESSAGETYPE_START_PING=11, MESSAGETYPE_STOP_PING=12, MESSAGETYPE_PURGE_INTERCEPTORS=13,
MESSAGETYPE_PENDING_TASKS=14 };

- message priority : enum { PRIORITY_LOW=0, PRIORITY_NORMAL=1, PRIORITY_HIGH=2, PRIORITY_URGENT=3 };

Example:

Here is the pseudocode to send the "on" command to a light switch.

We'll assume that the your device has #id 250 and the light switch has device #id 100

//////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

MyDevice.Connect(router_ip, 3450 /*port*/)

MyDevice.SendData("EVENT 250\n")

MyDevice.ReceiveData() //until you'll get a '\n' ; you should receive: "OK 250 IP=<device_ip_address> '\n';

//next: creating a message

//let's say MyData is an array of bytes

SerializeLong(MyData, 1234) //magic number

SerializeLong(MyData, 250) //my id

SerializeLong(MyData, 100) //the light switch

SerializeLong(MyData, 0) //not used now

SerializeLong(MyData, 192) //message id of command 'on'

SerializeLong(MyData, 1) //normal priority

SerializeLong(MyData, 1) //message type : command

SerializeLong(MyData, 0) //not used now

SerializeLong(MyData, 0) //not used now

SerializeUnsignedChar(MyData, 0) //not including children

SerializeLong(MyData, 0) //broadcast level : none

SerializeLong(MyData, 0) //don't retry

SerializeUnsignedChar(MyData, 0) //relative to sender false

SerializeLong(MyData, 3) //delivery confirmation

SerializeString(MyData, "") //device list to empty

SerializeUnsignedLong(MyData, 2) //2 parameters

SerializeLong(MyData, 98) //parameter type #98

SerializeString(MyData, "") //empty value

SerializeLong(MyData, 97) //parameter type #97

SerializeString(MyData, "") //empty value

SerializeUnsignedLong(MyData, 0) //no binary parameters

SerializeUnsignedLong(MyData, 0) //no extra messages

SerializeUnsignedLong(6789) //magic number

MyDevice.SendData("MESSAGE " + MyData.length() + '\n')

MyDevice.SendData(MyData)

MyDevice.ReceiveData() //until you'll get a '\n' ; you should receive: "OK" an error message

MyDevice.CloseConnection();

//////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

== How to serialize data-grids ==

(in work)

Complex objects:

1) DataGridCellSerializableData

- unsigned long, <sizeof(DataGridCellSerializableData)>

- unsigned long, <graphic_length>

- unsigned long, <message_length>

- unsigned long, <text_length>

- unsigned long, <value_length>

- unsigned long, <image_path_length>

- unsigned long, <number_of_attributes_length>

- unsigned long, <attributes_length>

- int, <alternate_color>

- unsigned long, <graphic_format>

- unsigned char, <selectable>

- int, <style_detail>

- int, <col_span>

- int, <row_span>

- unsigned char, <dont_fire_grid_event>

Enums:

- enum eGraphicFormat { GR_UNKNOWN=0, GR_JPG=1, GR_GIF=2, GR_TIF=3, GR_PNG=4, GR_MNG=5, GR_BMP=6, GR_OCG=7, GR_PFG=8 };

2) DataGridCell

- DataGridCellSerializableData, <datagrid_cell_serializable_data>

- array of chars, <text>

- array of chars, <value>

- array of bytes, <graphic_data>

- array of bytes, <message_data>

- array of chars, <image_path>

* foreach <cell_attribute>

* - array of chars ended with '\0' , <cell_attribute_name>

* - array of chars ended with '\0', <cell_attribute_value>

* end_foreach

3) DataGridTableSerializableData

- int, <total_number_of_columns>

- int, <total_number_of_rows>

- unsigned char, <keep_row_header>

- unsigned char, <keep_column_header>

- int, <column_count>

- int, <row_count>

- int, <starting_column>

- int, <starting_row>

- int, <cell_count>

4) DataGridTableCellIndex

- unsigned int, <column_row_type>

- unsigned int, <size>

5) DataGridTable

- unsigned long, <sizeof(DataGridTableSerializableData)>

- array of DataGridTableCellIndex, <col * row * sizeof(DataGridTableCellIndex)>

- array of DataGridCell, <col * row * serialized DataGridCell>

/*********************************************************************************/

Additional step: lzo compression/decompression

Note: can be disabled if compiled with DISABLE_LZO_DATAGRID

/*********************************************************************************/

Control LinuxMCE using an Infrared remote

2007-05-30T12:31:17Z

Tamjid:

<h1>How to set it up</h1>
In LinuxMCE Admin choose Wizard, Devices, Media Directors. Choose the type of Infrared Receiver you have from the pull-down. The list of choices are LIRC drivers, so you can also refer to http://lirc.org/ for details. Most use the "default" driver. Then add all the "Infrared remote controls you will use". You can have as many as you want and they will all work. LinuxMCE Admin will then add 1 Infrared Receiver device, and 1 device for each remote control you added. After adding any new devices chose Wizard, Restart and click Quick Reload Router so LinuxMCE starts using that device.

<h1>How to use it</h1>
When the media director starts you will see a graphical user interface with a menu of buttons. This is the "Orbiter". It's the same user interface as on the web-pads and PDA's. The Orbiter that the media director displays on your TV we call the On-screen Orbiter, to distinguish from the other roving Orbiters like the PDA's and mobile phones. What the buttons on the infrared remote control do depends largely on what you see on the On-Screen Orbiter. LinuxMCE is intelligent enough to know that sometimes you push buttons to control the media director's Orbiter, and sometimes you push buttons to control whatever media device you're using. LinuxMCE will handle all the translation for you. In other words you can use one universal remote control to LinuxMCE and other A/V Equipment.

Here's an example. Let's say you have a media director, which is also controlling your satellite TV box as well as a regular DVD player. The media director is controlling both of them via Infrared. You have a universal remote control which you added to LinuxMCE as described above. The On-screen Orbiter is visible on the TV. As you hit the up/down/left/right/enter buttons on the remote you will see that you can select the menu options on the Orbiter. You select the button to watch "Satellite TV", and the TV appears. Now when you hit up/down/left/right/enter LinuxMCE knows you obviously want to control the satellite tv box. So, when you press those buttons LinuxMCE translates the infrared codes into ones that your satellite tv box understands, and you will see the same arrows on the same remote control are now controlling the satellite TV. You hit 'Power Off', and the satellite box shuts off, and the Orbiter's menu is again visible. Now the arrows are again controlling the Orbiter. You choose the button to watch a DVD in your DVD Player. Now the same arrows are controlling the DVD player. And when you hit 'pause' the DVD player will pause, even though you're holding the LinuxMCE remote--not the DVD remote. LinuxMCE is translating everything for you so you don't have to juggle remote controls. Again you hit 'power' and the DVD turns off. Hit 'power' again and the orbiter shuts the TV off. Hit 'power' a third time and the media director itself turns off. This is even better than a universal remote control since you don't need to tell it what device you want to control--LinuxMCE figures it out on its own.

Although you can use all sorts of remote controls, and all have different buttons, they will all control LinuxMCE in a consistent manner. The media-specific buttons, like rewind/fastforward, play/pause, etc., will always control whatever media device you are currently listening to no matter what screen is visible on the on-screen Orbiter. Navigation buttons, like up/down/left/right/enter and the 10-key number pad, will control the currently active media device if the On-screen Orbiter is showing the remote control for that device. Otherwise it controls the On-screen Orbiter. When the main menu is visible on the Orbiter you can select scenarios with the up/down/left/right/enter buttons, or the 10-key pad. To use the 10-key pad, hit the type of scenario you want: the categories are always numbered as follows: 1=Lighting, 2=Media, 3=Climate, 4=Telecom, 5=Security, 6=Misc Then when the list of those scenarios appears, hit the scenario you want, such as 2 for the 2nd scenario. Thus 22 on the remote will start TV (2=Media, TV is always the 2nd option).

You can use different remote controls that have completely different layouts, but they will still control LinuxMCE in a consistent manner. For example you can use a Bang & Olufsen remote which only has a single set of up/down/left/right buttons, and LinuxMCE knows that when there is a menu on screen those buttons should move the highlighter around on the screen, and when there is not a menu on screen, those buttons are used for rewind fast-forward and skip up/down. The logic is all handled automatically so for the user it is a very intuitive experience, allowing all sorts of different devices to be controlled with all sorts of different remote controls without having to do any setup.

== Programmer's Guide ==

Be sure to read the How To Use It section above first.

As you can see, LinuxMCE provides a highly intelligent interpretation of infrared remote buttons, that automatically change their function based on what the user is doing, what type of remote control layout exists, and where the infrared codes are going. If you have ever worked with infrared remote controls, such as LIRC, you know that there is no standard, and all the remote controls have different buttons with different names. Therefore we had to create a database structure that allows for interpreting the different button names into commands which can change depending upon the context and the layout of the remote.

The DCE Devices (i.e. the LinuxMCE binary that is run to handle i/r reception) are all of the category Peripherals, Infrared Receivers.

In LinuxMCE Admin choose Advanced > Device Templates, and you can see the categories and devices in them. There is a separate folder for the LIRC drivers. In addition to a device for the i/r receiver, there is also a device for the i/r remote. The remote controls are of the type Peripherals > Remote Controls. Since the definition of the infrared codes for a remote control is stored within the remote control device, and that definition varies depending upon the type of receiver, you will see there is a separate subcategory for each type of receiver.

For example there is a folder "LIRC Remote Controls" that has all of the remote controls and definition files for the LIRC project. We also created our own DCE devices for other infrared receivers, such as IRTrans and Tira. Although these are supported within the lirc project, we found that we had better control and greater accuracy when we used the native SDKs for these receivers. So, for example, if you have an IRTrans receiver, and an XPMC remote, you have two possibilities. First you could add the LIRC receiver device, and the XPMC remote device that is within the LIRC remote category. In this case the remote control will be using an LIRC config file. Secondly you could add LinuxMCE's native IRTrans receiver device, and then pick the XMPC remote device that is within the IRTrans remotes category, which stores the button codes in a different format, that is in IRTrans' native format. When you are adding your infrared receiver and remote control using the LinuxMCE Admin Wizard/Devices/Media Directors page, the wizard automatically ensures that when you add a remote control it is the correct category.

For each remote control there is a device data "#59 Configuration" which has the remote controls configuration file, which defined all the infrared codes at each button will send and gives each code, or button, a name. So the XPMC remote within the LIRC category has a device data #59 that is the LIRC config file. The XPMC remote within the IRTrans category has a device data #59 that is the same buttons/codes, but in IRTrans format.

When the framework starts an IR receiver device, iIn general this device will first scan for all sister devices within the category remote control, and write out a configuration file. So, for example, when LIRC_DCE runs it finds all LIRC remote controls on that machine, grabs the device data "#59 Configuration" for every one of them and writes that out to a lirc.conf file, and then starts LIRC.

All the logic is in a base class called IRReceiverBase. All of LinuxMCE's infrared receiver devices use this same base class. So the actual code that is specific to each type of receiver is very small, usually around 20 lines. It only needs to write out the configuration file at start up, and then call the member function ReceivedCode within IRReceiverBase when a button is pushed. This function takes the name of the button as a parameter, and converts this into a message.

Since all of the receivers use a common base class to handle the logic, that also means that all of the translation between buttons and actions is also in a shared database. It does not matter whether you are using LIRC or some other infrared receiver, the translation is the same. There is no unified standard for what the buttons are called. The button "SkipFwd" may be called "Fwd", "Skip+", "Jump->", etc. The table RemoteMapping in the main mysql database, pluto_main, has a field Mapping which lists all the button aliases, followed by the command to be executed when any of those buttons is pushed. For example: chup;skipfwd;ChanUp;SkipNext;|0 -106 1 65 5 +1

Whenever any infrared receiver reports any of those button presses, the message "0 -106 1 65 5 +1" gets fired. The format of the message is the same as if you typed it with the MessageSend utility: ie from device, to device message type, message id, followed by parameters.

So if the user presses a button called ChanUp, a message will be sent to device -106 (media plugin) of type 1 (command) id 65 (Jump Position In Playlist) with parameter 5 (Value To Assign) set to "+1". This table is shared amongst all LinuxMCE users, and is updated every time your system upgrades versions. If you make your own manual changes to this table then the next time your core upgrades it will not upgrade the rows in that table that you modified, because SQL CVS does not, by default, overwrite your local changes with global ones. Therefore, if you have a new remote control with some new buttons that we have not yet mapped, it is recommended that you e-mail us or post us a message in the forum, with the button name and the message and then we can add it to our master database and then your system can remain in sync with other users enhancements. If you want to do some mapping that is just for you, you can change the table and know your changes will not be overwritten.

You'll note that the RemoteMapping table has 2 optional fields: ScreenType and RemoteLayout. When the IRReceiverBase base class is deciding what message to send in response to button press, it first looks for a more specific entry where the screen type matches the type of screen currently visible on the orbiter, and the remote layout matches the layout. The on-screen orbiters regularly send messages to the infrared receiver telling them what type of screen is currently visible, using the following codes: M=Main Menu, m=other menu, R=LinuxMCE Remote, r=Non-LinuxMCE remote, F=File Listing. This allows for buttons to behave differently depending upon what type of screen is visible. For example when the main menu is visible, the arrows on a remote control should send a message to the on-screen orbiter to move the highlight pointer around on the screen. However when the user is controlling an external piece of AV equipment, like a DVD player, the arrows should pass through to the DVD player so the user can control its own on-screen menu. Also the type of functionality can vary depending upon the layout of the remote. For example, Bang & Olufsen remotes are quite simple, there is only a single up/down/left/right buttons which are used both to navigate on-screen menus as well as to handle rewind fast-forward and skip. Other remotes have dedicated arrows and media navigation buttons. So one remote layout can be created for Bang & Olufsen-style remote, where the arrows control the menu when there is a menu on screen, and adjust the media when there is not. The remote layout is a device data "#110 Remote Layout" stored with the remote control

When IRReceiverBase looks for a mapping it first looks for records that match the current screen type and remote layout, and then revert to standard records (ie ScreenType and RemoteLayout are null) only if there are no matching results.

See also [[Add support for new remote controls]]