This program is not a "program with a GUI", nor is it a GUI for a particular program. Rather, it is a "Meta program", offering a GUI for a number of IR related programs, presently IrpMaster (advanced IR rendering program by myself), Makehex (older IR rendering program), DecodeIR (tries to identify an IR signal), and AnalyzeIR (which is my name of the Analyze-Function of the ExchangeIR-Library). Future extensions to other, possibly not yet written, programs are possible.
Note that I have written two different programs with quite similar names: IrMaster, the present one, a GUI, and IrpMaster, a library and a command line program, an IR signal render, but without a GUI. Please do not confuse.
In the sequel, the word "the program" will denote either the "shell" IrMaster, or the GUI together with its "clients" IrpMaster, Makehex, AnalyzeIR, and DecodeIR, as is hopefully clear from the context.
For someone with knowledge in the problem domain of IR signals and their parameterization, this program is believed to be very simple to use. This knowledge is assumed from the reader. Other can acquire that knowledge either from the JP1 Wiki or, e.g., this link.
So what can this program do: From a data base of known IR signals (essentially corresponding to the collected know-how of the community in machine readable form) IR signals corresponding to certain parameter values can be computed. Export files in different formats can be generated, for usage of other programs. For this, two alternative renders (my own IrpMaster as well as the older Makehex) are available. By using the clipboard, IR signals in Pronto format (for example from Internet articles) can be directly sent to the analyzers AnalyzeIR and DecodeIR. (To my knowledge, no other program presently allows this.) A computed signal can be sent proper hardware: For investigating possible non-documented IR signals of owned equipment, a "war dialer" can send whole parameter regions of IR signals. For this, hardware support in the form of GlobalCaché IRTrans, or LIRC is required. A simple calculator intended for simple computations on IR signal timings is provided.
Here is my TODO list, with both minor improvements, and suggestions for major "sub-projects".
Note that the screen shots are included as illustrations only; they may not depict the current program completely accurately.
The program, as well as this document, is copyright by myself. My copyright does not extend to the embedded "components" Analyze, Makehex, and DecodeIR. Makehex was written by John S. Fine (see LICENSE_makehex.txt), and has been translated to Java by Bengt Martensson. ExchangeIR was written by Graham Dixon and published under GPL3 license. Its Analyze-function has been translated to Java by Bengt Martensson. DecodeIR was originally written by John S. Fine, with later contributions from others. It is free software with undetermined license. IrpMaster depends on the run time functions of ANTLR3, which is free software with BSD license.
The "database file" IrpProtocols.ini is derived from DecodeIR.html, thus I do not claim copyright.
The Windows installer was built with Inno Setup, which is free software by Jordan Russel. To modify the user's path in Windows, the Inno extension modpath by Jared Breland, distributed under the GNU Lesser General Public License (LGPL), version 3.
The program and its documentation are licensed under the GNU General Public License version 3, making everyone free to use, study, improve, etc., under certain conditions.
IrMaster, and all but one of its third-party additions, are written in Java,
which means that it should run on every computer with a modern Java installed;
Windows, Linux, Macintosh, etc. Java 1.6 or later is required. The one
exception is DecodeIR, which is written in C++, and invoked as a shared library
(.dll in Windows, .so in Linux, etc). If DecodeIR is
not available on your platform this is not a major problem, as IrMaster will
work fine without it, just DecodeIR-related functions will be unavailable.
There is unfortunately no good make install or such in
the source distribution, so also source code distribution users are recommended
to install the binary distribution. Also, all necessary third-party components
are included in the binary distribution.
Both under Windows as well as under other operating systems, IrMaster (and IrpMaster) behave civilized, in that they do not write in the installation directory after the initial installation. In both cases (in contrast to the source distribution), the distribution contains everything needed including third party libraries like DecodeIR, AnalyzeIR, MakeHex (Java version) and its irp-files.
Under Windows, the properties are stored in
%LOCALAPPDATA%IrMasterIrMaster.properties.xml using Windows
Vista and later (on my Windows 7 system, this is %HOME%AppDataLocalIrMasterIrMaster.properties.xml), otherwise in
%APPDATA%IrMasterIrMaster.properties.xml. Using other operating
systems, it is stored under $HOME/.irmaster.properties.xml. It is
not deleted by uninstall. (If weird problems appear when updating, try
deleting this file.)
Download the Window setup
file, save, and double click. Accept the license. Select any installation
directory you like; suggested is C:Program FilesIrMaster. Unless
reason to do so, create the start menu folder, the desktop icon, and allow the
program to add the application directory to your path (for IrpMaster as command
line program). Administrator rights are probably needed, at least if you are
installing in a directory like "Program Files". (The should not be
needed otherwise, but Windows Vista and later are always good for a surprise...)
IrMaster can now be started from Start -> IrMaster ->
IrMaster, or from the desktop icon.
To uninstall, select the uninstall option from the Start menu. Very pedantic people may like to delete the properties file too, see above.
Create an installation directory (suggestion;
/usr/local/irmaster, and unpack the current binary distribution into
it. Examine the wrapper irmaster.sh, and make desired changes to
it with your favorite text editor. Then make two symbolic links from a directory
in the path (suggestion; /usr/local/bin to the newly installed
irmaster.sh, using the names irmaster and irpmaster. Example (using the suggested directories)
cd /usr/local/bin ln -s ../irmaster/irmaster.sh irmaster ln -s ../irmaster/irmaster.sh irpmaster
(su (or sudo) may be necessary to install in the
desired locations.)
To uninstall, just delete the files. Very pedantic people may like to delete the properties file too, see above.
Both under Windows and Unix-like systems, a wrapper for the command line
program IrpMaster is installed. The user can simply open a command window
(called anything like "xterm", "Terminal", "Shell", "DOS-Box", "cmd",...) and
in that command window can call the program IrpMaster by simply typing
irpmaster, followed by its arguments. See the screen shot below,
that shows the generation of the Pronto form of a NEC1 signal for device 12,
subdevice 34, command number 56,
together with subsequent invocation of DecodeIR on the computed result. (The
output on non-windows system is entirely similar.)
As stated previously, for anyone familiar with the problem domain, this program is believed to be easy to use. Almost all user interface elements have toolhelp texts. In what follows, we will not attempt to explain every detail of the user interface, but rather concentrate on the concepts. Furthermore, it is possible that new elements and functionality has been implemented since the documentation was written.
This program does not disturb the user with a number of annoying, often modal, pop ups, but directs errors, warnings, and status outputs to the console window, taking up the lower third of the main window. There is a context menu for the console, accessible by pressing the right mouse button in it.
In the upper row, there are four pull-down menus, named File, Edit, Options, and Help. Their usage is believed to be self explanatory, with the exception of the entries in the Options menu. The latter mimics the Options subpane, and are explained later.
The main window is composed of presently four sub panes denoted by "IR Protocols", Output HW", "IRCalc", and "Options" respectively. These will be discussed now.
In the upper third of this pane, a render program (IrpMaster or Makehex) can be selected, together with the IR protocol identified by name, and the parameters D ("device", in almost all protocols), S ("sub-device", not in all protocols), F ("function", also called command number or obc, present in almost all protocols), as well as "T", toggle (in general 0 or 1, only in a few protocols). These number can be entered as decimal numbers, or, by prepending "0x", as hexadecimal numbers. Note that the supported protocols are different between the different rendering engines. Not all possibilities of IrMaster are available when using the simpler render Makehex.
The lower two thirds of the window is occupied by another pane setup, consisting of the sub-panes "Analyze", "Export", and "War dialer".
By pressing "Render", the signal is computed, and the middle window is filled with the Pronto representation of it. Pressing "Decode" sends the Pronto representation to DecodeIR. Pressing "Analyze" sends it to AnalyzeIR. In both cases, the programs will send their output to the console window, as can be seen below.
Using context menus, the result can be sent to the clipboard or saved to a file, after invoking a file selector. It is also possible to fill the code window from the clipboard, or to import a file ict-format, for example from the IRScope-Program. Note that an ICT file produce by IRScope may contain several IR signals, which cannot be easily separated. They will be imported as one giant signals, with all the gaps and spaces concatenated together. This is a flaw in the IRScope program.
The left part of the middle window allows for sending the code in the code window to hardware, presently GlobalCaché, IRTrans, and LIRC (requires a patch), any number of times the user desires. These run in their own threads, and can be stopped anytime.
Important: In all cases, DecodeIR/Analyze operates on the actual Pronto code in the middle window, which may even be manually manipulated by the (sufficiently knowledgeable :-) user. Presently, there is no possibility to short-circuit directly from the signal rendering to decoding/analyzing. Also note that transforming the signal to the Pronto format may introduce some rounding errors causing DecodeIR to fail to indicate some IR signals it would otherwise identify.
Using the export pane, export files can be generated. These allow e.g.
other programs to use the computed results. Using IrpMaster, exports
can be generated in text files, XML files, and LIRC-format, the first two both
in Pronto format and in
"raw" format (timings in
microseconds, positive for pulses, negative for gaps). The LIRC-exports are in
lirc.conf-format using the raw format. They can be concatenated together and
used as the LIRC server
data base, typically /etc/lirc/lircd.conf. Of courses, they can
also be used with WinLirc. Optionally, for
protocols with toggles, both toggle pairs may optionally be included in
the export file by selecting the "Generate toggle pairs"-option. Export file
names are either user selected from a file
selector, or, if "Automatic file names" has been selected,
automatically generated.
The export is performed by pressing the "Export" button. The "..."-marked button allows for manually selecting the export directory. It is recommended to create a new, empty directory for the exports. The just-created export file can be immediately inspected by pressing the "View Export"-button, which will open it in the "standard way" of the used operating system. The "Open" button similarly opens the operating systems standard directory browser (Windows Explorer, Konquistador, Nautilus,...) on the export directory.
This functionality is intended for the search for undocumented IR commands for customer equipment. It allows for sending a whole interval of IR signals to the equipment, and taking notes when something reacts on the sent signal. The "Start" and "Stop" functions are probably self explaining; the "Pause" button allows for interrupting and later resuming, but is presently not implemented. A note-taking function is planned but presently not implemented: when "Edit" is pressed, a "Document" pops up with current IR signal and time, allowing the user to write a note on that signal, which can later be saved by "Save".
The sub-panes of this pane allows for the selection and configuration of the employed IR hardware.
This allows for configuring GlobalCaché support. The Discover-button attempts to find the identifying beacon of GlobalCaché modules (only present on recent firmware). If successful, will fill in the IP-Box, its model, the default IR-module and IR-port (see the GlobalCaché API specification for the exact meaning of these terms). In any case, the IP Name/address window, the module and port selection can be changed manually. The Browse-button directs the selected browser to the built-in WWW-server of the module, while the "Stop IR"-Button allows the interruption of ongoing transmission, possibly initiated from another source.
To be fully usable for IrMaster, the LIRC server has to be extended to be
able to cope with CCF signal not residing in the local data base, but sent from
a client like IrMaster, thus mimicing the function of e.g. a
GlobalCaché. The needed modification ("patch") is in detail described here. However, even without
this patch, the configuration page can be used to send the predefined commands
(i.e. residing it its data base lirc.conf). It can be considered
as a GUI version of
the irsend
command.
The LIRC server needs to be started in network listening mode with
the -l or --listen option. Default TCP port is
8765.
After entering IP-Address or name, and port (stay with 8765 unless a reason
to do otherwise), press the "Read" button. This will query the LIRC server for
its version (to replace the grayed out "
Due to LIRC's pecular form of API stop command, the "Stop IR" command presently does not work. See this thread in the LIRC mailing list for a background.
The configuration of IRTrans is similar to LIRC, so it will be described more briefly.
Enter IP name or -address and select an IR port (default "intern"). If the Ethernet IRTrans contains an "IR Database" (which is a slightly misleading term for an internal flash memory, that can be filled by the user), its commands can be sent from this pane. By pressing the "Read" button, the known remotes and commands are loaded, and the version of the IRTrans displayed. The selected command can now be sent by the "Send" button. (However, this functionality is otherwise not used by IrMaster.) Selecting "IRTrans" on the "Analyze" and "War dialer" pane should now work. The IRTrans module is then accessed using the UDP text mode.
This pane allows for some often reoccurring interactive computations.
The left hand side computes, for a number given in first row either as
decimal or hexadecimal its (one-) complement (in 8, 16, or 32 bits), its
"reverse"
(java.lang.Integer.reverse(): the value obtained by reversing the
order of the bits in the two's complement binary representation of the
specified int value). Furthermore, the EFC and EFC5 functions of the JP1-world
are computed, together with their inverses.
The right hand side computes, for a carrier frequency given either in Hz or as a Pronto code (i.e., the second number in the CCF), either the time for a given number of periods (entered as decimal or hexadecimal), or the number of periods as a function of the time entered.
This allows for selecting some parameters crucial for the operation of the program. Of the parameters displayed above, note that "debug code" and "verbose" are not properties in the sense that they are saved in the properties file, while the others are.
The option "disregard repeat mins" is described in the IrpMaster documentation.
Normal usage is just to double click on the jar-file, or possibly on some wrapper invoking that jar file. However, there are some command line arguments that can be useful either if invoking from the command line, or in writing wrappers, or when configuring custom commands in Windows.
Usage:
irmaster [-v|--verbose] [-d|--debug debugcode] [-p|--properties propertyfile] [--version|--help]
or
irmaster IrpMaster
The options --version and --help work as they are
expected to work in the GNU
coding standards for command line interfaces: The -v/--verbose
option set the verbose flag, causing commands like sending to IR
hardware printing some messages in the console. The debug option
-d/--debug
takes an argument, and the result is stuffed into the debug parameter
in the program. This is passed to invoked programs that are free to
interpret it any way it likes. For example, here is how IrpMaster
interprets the debug variable. This option is likely of interest only
to developers, who have to look in the code to see what is sensible.
The second form invokes IrpMaster as a the command line program on the rest of the arguments. It is a convenience feature for just having one user entry point in the distributed jar file.