| | |
| Make/Model | Device Version | Connection Type |
| Various | N/A | Various |
CQC supports a set of IR devices. Since the bulk of the required software architecture is the same, CQC uses a generic client side IR driver for all IR blaster or receiver devices that it supports. Some devices might include IR control within the context of a broader set of functionality, but this interface will only manage it's IR functionality. This page describes the common features of the IR driver and IR architecture first, then specific issues related to the various supported IR devices are provided.
- NOTE that there are some RF devices here as well. Though they are obviously not IR based, their usage so cleanly fits into the IR scenario that it just didn't make sense to create a completely new driver and interface for them.
The client side IR interfaces allow you to do a few different things
- IR/RF Receiving. For devices that support IR/RF receiving, which is the ability to make CQC do things in response to a signal, it lets you set up the actions you want to invoke and to train CQC for the signals that you want to invoke those actions.
- Loading and managing 'device models'. CQC provides a repository of 'device models' on the Charmed Quark web site. These are files of pre-configured commands for a given model of device that you might want to control. This driver allows you to import these files into your CQC system, and to load them into blaster devices to use for blasting at devices.
- Training in commands. If we don't provide a device model for your particular device, you can train them in yourself using this interface, to create your own device models.
The client interface is implemented as a tabbed window. There is one tab for blaster functionality and one tab for receiver functionality. If the device supports both, it will have both tabs. Else, it will have one or the other. Note that the title text and the icons displayed in these examples are for a given driver and driver name and will vary will depend on the actual device being controlled and the name given to the driver instance.
The following devices are currently supported:
Receiver Tab
Here is the receiver tab. It provides you with buttons to create new mappings, delete existing mappings, or edit existing mappings. A mapping is an association between the IR/RF signal received (usually meaning the button you press on a remote control) and the CQC action that you want CQC to invoke when you press it. You create the mapping by 'training' CQC, i.e. telling it which signal should trigger the action, much like you would train a learning remote.
To create a new mapping, press the New button, and you will be presented with the user action configuration dialog. This dialog is used in a number of places with CQC, so it is documented separately. You should set up the action you want to invoke, and then save the results. When you save, you will be presented with the training dialog.
You should press the key that you want to use to invoke this event. According to the device, it will display different instructions to help you insure that CQC will get a good read of the data, and you should read the manufacturers instructions on good training etiquette as well. Generally it will ask you just press the button a few times in a row so that it can be sure it is seeing a consistent signal. Once CQC sees a clean read, the dialog box will go away and you will go back to the main receiver tab, and should see the new action title in the list.
- Note that sometimes if you hold the button down a little too long or press it a few times more than required, you might actually invoke the action you just configured, because after training ends, the driver goes back to watching for IR events to trigger and it might see those extra presses as a triggering IR event.
You can use the Delete and Edit buttons to remove existing mappings, or to edit mappings that are already present. If you edit, you will be allowed first to edit the action, and once you save those changes you will be asked if you want to retrain the event. If not, the new action data will be saved under the same mapped event. Else, you can retrain the mapping to be keyed by a different signal. If you just want to retrain, then just press Save without making any actual changes to the action data.
Once you've trained CQC for the event mapping, you can then point the remote at the receiver (not too close, use it from a normal distance) and press the button you trained, and it should do the action. If not, you will have to check the logs to find out what went wrong.
Be aware that when you invoke a mapped event, that action is run on the machine that is hosting the server side IR driver for the device, not necessarily on the local machine. So you don't have to be logged in or running any CQC client side apps on that machine to invoke the IR events, the driver is watching for them all the time. Because of this, the events run in the background and there is no way to visually report errors that occur in IR invoked actions, and you just have to check the logs for diagnosis of the problem.
Blaster Tab
Here is the IR blaster tab, which is considerably more complex, again noting that the title and icon displayed depends on the device being controlled and the moniker given to the driver instance.
IR/RF blaster devices, in CQC, deal with sets of IR commands called "Device Models", each of which contains the IR/RF commands to deal with a particular model of controlled device. So there might be a device model called "Denon AVR-1600" which contains the IR commands to control, as you might expect, a Denon AVR-1600 device. Because of the large number of such device models that can exist, CQC does not ship any in the product. Instead, you can download them from the CQC IR repository pages (see the Import Libraries section below.) These files are in XML format, and you can use the Import feature of the IR driver's blaster interface to import them into your CQC system. Once imported, they are available to be uploaded to any blasters (of the same IR blaster type) in your system.
If your device is not in the repository, and your blaster is a trainable one, you can build a device model of your own. You are encouraged to contribute your device models back to CQC so that they can be put into the repository and others can benefit from them. Try to look at some other device models for the same sort of device and use the same naming conventions, to make it easier for people to swap devices without invalidating their configured actions and macros.
To import a device model, use the Models menu and select the Import... item. This will open the local file browsing dialog box and allow you to select a local IR device model import file, which it will open into the model editing dialog. If you want to create your own model, press the Create button and enter the name of the model when prompted, or press Edit to edit an existing model.
The name of the model should be basically the actual model name of the device, though some characters used in a model name might not be accepted because they are illegal in a file name, but get as close as you can. Don't include the make in the name, just the model, the make will be one of the values provided later. So don't name it Denon AVR-1601, name it AVR-1601.
The Create or Import buttons will take you to the model editing dialog, which looks like this:
If you imported a model, this dialog box will be completely filled out with the information you imported. If you are creating a model, then you should fill in the make and description fields, and select the appropriate category for the device. The description should follow the style above, which is the make, the model, and the type in a nicely worded, short description. In this case, we are creating a new model, so the command list is empty.
To add a new command to the model, press the New button. You will be asked to enter a name for this new command. Enter the name and press the Save button. This will pop up the training dialog, which looks like the one below. As with receiver training, the correct way to train each device differs, so the instructions will vary according to the type of device.
At this point the blaster is waiting for you to train it for an IR command. So press the IR button that you want to associate with this command. You might have to press it more than once if the device isn't getting a good read. When it gets a good read of the data, the dialog will disappear and you will see the new command show up in the model editing dialog.
You can now continue to add commands to the model, delete commands, retrain the commands, or test them by causing the blaster to send them interactively by highlighting the command pressing the Test button. Obviously you want to add more than one command, so that the device can be fully controlled, but for our demonstration purposes it is sufficient.
The Repeat value indicates how many times you want each command for this device model to be sent. It's not uncommon to send the data a two or three times, in order to make sure that the command is seen reliably. This is more important for open air blasters. For zoned blasters that use stick-on emitters, you may want to reduce this to one in order to prevent the commands from being triggered multiple times, and to allow the commands to complete more quickly because only one instance of the data needs to be sent. For open air blasters, the default of two is usually good. Note that this indicates how many times total that the data is sent, not how many times it will be repeated after the first time. So a value of two means it will be sent two times.
The Save button will load the device model into the server side driver of the IR device you are configuring, on the assumption that you imported for that purpose anyway. So when you go back to the main blaster tab, you will see that the model is loaded up for this IR device, as in our example below where we saved the AVR-1600 model we were working on (though in this case with all of the commands in place instead of just the one we created above.) It will also save it to the Master Server, which is discussed below.
By loading a model into a blaster device driver, you make the commands of that model available to be blasted via the device that driver controls. The list of models loaded on this particular blaster device are available in the combo box at the top of the blaster tab. Use it to select from among the loaded models. You can use the Unload button to unload models from the device if you don't need to use it anymore. It will still be on the Master Server so you can load it up again later, it just doesn't get loaded into the target blaster driver, and therefore will not be available to invoke. When you unload a model, you will be asked if you also want to delete it from the Master Server. If you no longer need that model, say yes to have it removed.
To load a model that has already been created or imported into CQC, use the Load button, and you will be presented with a model selection dialog. Each time you save a model, it will be loaded to the Master Server and therefore is available subsequently without importing it, you can just load it from your own IR repository.
In this case, it is a bit of overkill, since it only shows the one model we've created. But once you have imported a good number of models, there can be a relatively long list, so it provides a filtering mechanism. You can filter by make and/or by category, by just checking the box for each filter and selecting the value to filter by. This can help you quickly get to the model that you want.
Zoned Blasters
There are two basic types of IR/RF blasters, open air and zoned. Open air blasters are like the remotes you are used to using, in that they blast a signal out into the air and it hits every device that is in basic line of sight, or even indirectly via reflections off of walls. For most situations, this is not a problem, since each device has its own signal format and they ignore those that aren't of their type. But, if you have more than one instance of the same device in your system, and you want to control them separately, that's a problem with open air blasters.
To deal with this, some blasters don't blast out into the air, but instead just have places where you can plug little stick on blasters into them, and they send their signal out to these small blasters that are then stuck on the front of the devices you want to control. This way, the signal going out to a particular blaster stick-on won't be seen by any other device.
Each of the plugs provided by the blaster is called a 'zone' in CQC's parlance, and you can address them individually. In the images above of the blaster tab and edit dialog you can see that there is a spin box via which you can select the zone you want to use. If the blaster is open air, there will be a single entry of zone 1. If the blaster supports zones, then you can select the zone you want to tests to be sent through.
Import Libraries
In some cases you will not need to create a device model manually, because CQC provides a set of IR libraries for each blaster type it supports. These libraries provide files in CQC's IR Import/Export format, which is an XML based format, that you can import into CQC and save. It then will be available for use in your IR blaster. Each blaster type supported has it's own IR library, since the files are specific to a particular blaster type, so be sure to pick the appropriate library for your blaster type.
These are available from the Charmed Quark web site. Use the Downloads menu bar item, and the select the IR Device Models sub-section. Choose your particular type of blaster to get to the device models for your device.
If you don't find your device in the library, and end up creating one yourself, please consider contributing the file back to Charmed Quark so that we can add it to the library and other users can benefit from it. Try to use similar naming style for commands as used in existing models of the same genre of device, to make it easier for people to swap devices.
This section will cover installation issues for those devices that have special considerations.
R2DI IR500P
The IR500P is a PCI board and uses a device driver that makes it look like a serial port. You can get the driver here. To install it, you want to unzip this file somewhere, then shutdown your system and install the board. When it comes back up and indicates new hardware is available and asks where the driver is, point it at the top level directory of the unzipped driver data. Don't point it into the WinNT4 sub-directory of the driver. This will create a new serial port, which you can find by looking at the Windows device manager to see what the new port number is (or change it if required.)
RTI RP6
The RP6 is an RF based system and CQC doesn't actually get involved in the actual receiving of RF signals. Instead, it talks to a controller which allows you to device ASCII strings that the controller will send when it sees a given button press on the remote control. So you can set up any arbitrary ASCII strings that you want. Other that that, from CQC's perspective, it acts just like an IR receiving device. You train the same way, it's just that CQC sees your ASCII strings as the 'signals'. You should carefully think out the format of the strings you use. Probably something in the form of a hierarchical path would be a good choice, e.g. "/LivingRoom/TV/PowerOn" and "/Kitchen/Lights/Dim" and so forth. This will make it easy to understand, just from seeing the string, what it does and in what area of the house.
This section will cover issues for each of the available devices, where applicable.
GC-100
Since some of the IR ports can be configured as sensors instead of blasters, this can reduce the blaster zones available. If the device has say 6 IR ports, and the second one is a sensor, then there are 5 zones, numbered 1 through 5. So you have to be aware of how CQC zone numbers map to IR ports. In this case zone 2 would be port 3, zone 3 port 4, and so forth because the second port was removed from the zone list. Generally, it would be best to configure the ports at the end to be sensors (if any are) so that the zone numbers match the IR port numbers.
Note that the GC-100 can also contain serial ports, but those cannot currently be used by CQC because there is no way to make them look like standard serial ports. They are only accessible at this time via socket commands.
The GC-100 is not trainable, so it can only use IR models by importing them via the CQC IR export format, which you can get from the CQC web page. We can convert codes learned into a UIRT for you if needed.
IRMan/Ira-2
The IRMan/Ira-2 devices are one way, in that they only talk to CQC. CQC cannot really poll them to make sure that they are still alive and healthy. So there is always the chance that the device has gone offline and CQC doesn't realize it. Periodically the driver will re-do the connection handshake to try to determine it is still alive, but it can't do that too often since the device won't be available to you while that is happening.
IR500P
The IR500P has IR receiving capability, but it is not supported yet in our driver. We will address when possible.
RTI RP6
The RP6 is completely one way, i.e. despite the fact that it is a serially connected device, it just sends out data. CQC cannot ask it anything and will have no idea if the device becomes unplugged or inoperable.
USB-UIRT
The UIRT has different training requirements for receiving vs. blasting. For blaster training, you want to use the 'kissing' method, generally used by learning remotes, i.e. sit the UIRT on a flat surface, sit the remote on the surface, so that it's IR emitter on the top is a couple inches from the front of the UIRT. Then press and hold till the signal is trained.
Blaster training is also quite sensitive to ambient light. If there is any bright sunlight coming in the windows, it can interfere with blaster training pretty easily, so try to shade the UIRT from bright ambient light during blaster training.
For receiver training this is not necessary and it seems happy to be trained from a more normal distance, and that might be preferable so that the signal looks more similar to what it will be like in normal usage.
This section will cover connection details for each of the available devices, where applicable.
GC-100
The GC-100 sits on the Ethernet network and looks like a regular network node. You configure it via a web page interface and give it a particular IP address. When you load the GC-100 driver you will be asked for the address and port information that you configured the GC-100 for. Obviously the connection is very fast since it's a socket based interface. Generally speaking, it is best to just turn off automatic notifications, since CQC polls the device anyway and it does so quickly. This devices will have 3 or 6 8th" plugs for configurable blaster/sensor zones.
IRMan/Ira-2
These use a standard straight through serial cable. You must use a standard serial cable. The commonly used three wire minimalist cable will not work, because these require the host computer to twiddle DTR/RTS lines during communications. The port settings are fixed at 9600 baud rate 8 bits, no parity, one stop bit, no flow control.
IR500P
The IR500P is a PCI card, but it comes with a device driver that makes the device look like a serial port to CQC. So once you load that driver, check your Windows device manager to see what serial port it is on. Select that port when installing the device. It has five 8th" plugs, four are for configurable blaster/sensor zones, and the fifth is for a receiver unit (currently not supported by CQC.)
The top plug (looking at the back of the board as it would be installed, i.e. the one nearest the mounting bracket top), is an IR receiver port which is not supported. The others are blaster/sensor ports one through four, moving downward, so the bottom one is port four. If you assigned all the zones to be blasters, then the ports are directly matched to the blaster zones, i.e. the second from the top is zone one, and the bottom one is zone four. If you configured zone one and two as blasters, and zones two and four as sensors, then the second to the top port is blaster zone one, and the second from the bottom is blaster zone two.
RTI PP6
The RP6 just uses a standard serial cable for connection. It sends out the ASCII strings that you have configured in the RP6 controller.
USB-UIRT
The USB-UIRT, of course, is USB based, so it is simple to use and the connection is very fast because it is a programmatic interface. You must have installed the support DLL that comes with the USB-UIRT or the driver will not be able to find it and will not be able to connect to the device. The CQC driver loads the UIRT DLL dynamically, so that it will not completely fail to load if the DLL is not located. It is expected that the DLL is in the system path, as it will be if it is installed normally.
This section lists the fields that the driver makes available, their types, minimum and maximum values, etc... These are the common fields that are supported by all of the blaster drivers.
Name Type R/W Description/Limits FirmwareVer String R If the device allows CQC to query a firmware version, this field will hold it. Else, this field will be an empty string. Invoke String W This command is a way to make a blaster device send a particular IR command from a particular IR model. The format is discussed below. TrainingMode Boolean R Mostly for internal use, this indicates whether the device is currently in training mode or not. GC-100 specific fields
IRSensorX Boolean R Where X is the sensor number. Each IR port, from left to right, which is configured as a sensor will be given a sequential number starting at 1. So the first sensor is IRSensor1, the second is IRSensor2, and so forth. RelayX Boolean R/W Where X is the relay number. Each contact closure, from left to right, will be given a sequential number starting at one. So the first relay is Relay1, the next is Relay2 and so forth. IR500P specific fields
SensorX Boolean R Where X is the sensor number. There are 4 zones on the IR500P. If the second zone, for instance, is set up to be a sensor, then you will have a Sensor2 field that reflects the value of that sensor. The Invoke field is a formatted string that allows you to cause a blaster device to send a particular IR command from a particular IR model. The format of the command is:
model.commandSo it is the model name followed by the command name. If the model is not loaded into the target blaster, or it is but doesn't have a command of the given name, the value will be rejected and you will get an error returned. In the example that was used above, we could toggle the power by sending the follow to the Invoke field:
AVR-1600.Toggle PowerIf the blaster is zoned, then you need to indicate which zone you want to the command to go to. You do this by appending a colon and the zone number. By default you get zone 1, which is the only zone that an open air blaster supports, which is why the format above works without any explicit zone. To do the above command and send it to zone 2 of the blaster, you would do:
AVR-1600.Toggle Power:2The zones are from 1 to how many zones the device supports. For a device like the IR500P, where sensor and blaster zone numbers are intermixed, this will be the absolute zone number. For the GC-100, where the sensor zones are numbered separately from the blaster zones, this will be the logical blaster zone, not the absolute zone number.
