How to set it up

In the LinuxMCE Admin Website, go to Wizard > Devices > A/V equipment. If you haven't already added the TV and whatever cable/satellite box you use for the tuning, click 'Add Device'. Choose the manufacturer, category, and then model of the device. Then click 'Add Device'.

If your model is not in the list, then after choosing the manufacturer and category, type the model name in the box under the models column and click 'Add' to create your own Device Template, which means a definition of a device that explains the properties of this model. Be sure popups are not blocked--a popup window will appear asking how many tuners this TV has (see next paragraph for an explanation). After you add the Device Template for this model, then select it from the model list and click 'Add Device' to add it to your installation. Since this is a new Device Template, on the A/V equipment page be sure to click the 'A/V Properties' button for this device to tell LinuxMCE about this Device Template, such as what inputs it has, whether you will control it with infrared, and so on.

Note: You will see that a TV is actually treated as multiple devices: the display device, and also a separate device for the tuner(s) inside the TV. This may seem confusing, but it's necessary. Many TV's have multiple tuners, and different tuners may have different video sources; one may be hooked up to cable, and another one to an antenna. And those tuners use different inputs on the TV. Therefore, LinuxMCE treats the tuners as "embedded devices" within the TV. When you want to watch TV, you will actually be telling LinuxMCE you want to use a tuner within the TV. For example, you will say you want to use Tuner #1 (cable), or Tuner #2 (antenna), etc. Therefore when you add a new Device Template for a TV, LinuxMCE Admin will ask how many tuners it has. Receivers are treated the same way since they can also have multiple tuners inside, like FM, AM, Weather Band, Satellite, etc.

On the A/V equipment page you also need to specify the A/V Connections, also known as "Pipes". You can do it using the "Edit" link in the "Pipes" column, or do it graphically by drawing lines between your devices by clicking the "Connection Wizard" link. If you added a cable or satellite box, the video pipe from the box will be the TV that it's connected to, and you choose the input on the TV you used, such as "Video 2". If you want the sound to come out of the TV too, the audio pipe will also go to the TV on the same input. If you want the sound to come out of your receiver, then the audio pipe goes to the receiver. If you're not using an external satellite/cable box, but rather the TV's internal tuner, you'll see that the internal tuner already has an audio/video pipe to the TV. If you don't want the sound to come out of the TV's internal speakers but rather use a stereo receiver, then change the audio pipe for the tuner to go to the receiver instead.

The "Controlled Via" pull-down should be set to whatever device is going to be responsible for controlling this piece of equipment. If this is controlled via infrared the "Controlled Via" device is the infrared device you are using to control it (added on the Wizard > Devices > Interfaces page). If this a/v equipment is controllable by RS232 or USB, the Controlled Via should be the PC computer it is connected to. If it is controlled via Ethernet, it can be any computer on which you want to run the device driver, usually it's the Core.

If you have multiple TV sources in your home, such as Cable and Satellite, you may want to click the "Media Providers" link to specify the providers. This step isn't necessary. However if you do add Media Providers, then for each piece of a/v equipment that is a source device you can specify what Media Provider it uses (this box provides "Cable TV" and this "Satellite TV"). The advantage of doing this is that then follow-me media, move media and broadcast are more accurate. If LinuxMCE is able to know that you were watching channel 35 on a device that uses Media Provider "satellite tv", then when the user wants to move or broadcast this media to other rooms, LinuxMCE knows to find devices in those rooms that also use provider "satellite tv". Otherwise LinuxMCE may end up picking a cable tv device instead. If you only have one provider for tv then there is no reason to worry about specifying a provider.

Next go to the Wizard > Scenarios > Media Scenarios page. Every media scenario will appear as a button on the Orbiters, so we need to add a media scenario in the room (aka Entertainment Area) where you want to use this TV. Under 'Add Scenario' type the description you want on the button, such as "Live TV", "Cable, etc". Choose the Entertainment Area, or room, then choose the source device. This should be the tuner in the TV, or a satellite or cable box. Also choose the type of media, "Live TV" in this case. If there is more than one remote control interface that will wok with this device you'll have a pull-down for that too. The next time you regen the UI for this Orbiter (see Wizard > Devices > Orbiters), the button will appear.

After you add new devices, you need to go to Wizard > Restart and click "Quick Reload Router" so DCERouter starts using the new devices you just added.

How to use it

Just touch the button you created with the Media Scenarios above. It will appear on all the Orbiters for the room (Entertainment Area) you added it to. LinuxMCE will automatically turn on all the appropriate devices and set their inputs based on the A/V connections you specified in LinuxMCE Admin.

If the A/V equipment is controlled in some way that LinuxMCE can get feedback from it, such as RS232 or Ethernet, then you can also physically turn on or adjust any relevant device and LinuxMCE will figure out automatically what you want to do. For example, if you turn on the satellite box by hand, LinuxMCE knows you want to use it and will automatically turn on the tv and receiver, set the inputs, and put the remote control on the orbiters for you. Or, if you switch the input on the receiver to "DBS", which your satellite box is connected, LinuxMCE also knows that means you want to watch Satellite TV and will set everything up for you. However this functionality is not possible with a/v equipment that is controlled via infrared since i/r is 1-way communication; LinuxMCE can only send it commands, but has no way to know when you are controlling it manually.

Programmer's guide

The Media Scenario will send a "MH Play Media" command to the media plugin. The media plugin will then find a media handler plugin that knows how to handle that type of media. Tightly integrated media devices, like Xine or Myth, have their own media handler plugins that are intelligent and know how to do things like synchronize multiple rooms to the same media, move media between rooms and respect stopping/starting at the same place and so on. Generic A/V devices like TV's and satellite boxes are nearly always by the media handler "Generic NonLinuxMCE Media", which is built into the media plugin itself. This media handler is very simple--it just forwards the command to the device.

When a device gets an "ON" command, DCERouter router calls the function "HandleCommandPipes". This is what knows how to turn on all the devices and set their inputs based on the a/v pipes you specified on the a/v equipment page. This is also why the tuners need to be treated as separate embedded devices within the TV, since each one will use different inputs.

The table MediaType_DesignObj has the standard remote controls for each type of Media, and the table DeviceTemplate_MediaType_DesignObj has custom remote controls more appropriate for a given device. When adding the media scenario if there is more than 1 remote control that can be used to control this type of media on this device, the user can choose from the list.

The message translation class is used within the infrared devices (like gc100), and within GSD (generic serial device) to translate commands and handle things like toggle vs discrete inputs. Devices which are controlled using GSD and a serial/ethernet interface will fire events AV_Input_Changed and Device_OnOff which Media_Plugin has interceptors for and will use the a/v pipes to figure out what device you're trying to use.