Advice on Dealing with Chaos when Programming AMX systems

Marat Gilyazetdinov
Chief Programmer iRidium Mobile Ltd.

This article contains advice to help you organize projects. It is quite common to ignore the standardized approach because there may be a misunderstanding to the benefits gained from doing so. Ultimately keeping your work organized will allow you to be more effective when dealing with multiple projects.

In my opinion, the most critical component of implementing an AMX automation system is the system programming. On average, an AMX installer is engaged in 3-5 projects at a time. This can make it hard to concentrate on one project. A programmer has to turn his attention to many different tasks and maybe he is taking on a development task that has been started by another programmer. In either case he has to establish what has been done already, what errors have to be corrected, what to do next, etc. The process of switching between different tasks or projects can be quite time consuming. This wasted time will either extend the development time or may even lead the programmer to do a rushed job. As you may very well know a rushed job usually introduces mistakes into the code. These mistakes have to be corrected. This will delay the completion date and will generally result in an unhappy customer.

Based on my own experience I would like to share a few ideas on how to improve programmer’s efficiency and minimize the number of errors in his work. The majority of advice is generally known but unfortunately many installers ignore it because they are not aware of or reluctant to do so.

Keeping a journal. When turning from one job to another each programmer has to establish what has already been done, what has to be done next, what problems were encountered and whether they still need to be fixed. The journal keeps all important information about the programming process: date and time of starting/finishing works, what is done, what has to be done, what problems are found, possible ways of solving the problems. The journal can be kept on paper or your PC. It allows you to delegate your work to other programmers who will be able to understand the current status of your project and quickly pickup you left off. Keeping the journal will save a great deal of your time and thus you will avoid the unnecessary rush. It will help you to monitor the stages of your projects and see the scope of the work you are to do.

Example of the journal created in MS Excel:

06.03.2012	Added the Panasonic PT-AR100EA module to the 1st RS232 port.
	The slot of port 1 of RS232: 2 and 3 contacts are turned, installed the adapter, tell the installers to solder the contacts correctly.
	Added BR control of the SONY BDP-S495 player to the 1st port.
	Added control of the Marantz SR7005 receiver to the 2nd port of RS232.
	In the module of controlling the receiver: finish the part for working with radio.
	The customer asked to add the mode of listening to BR-Audio and radio to the mode of watching videos.
	Add the page of waiting for turning the projector ON/OFF to the project.
	The Play and Pause codes are mixed up in the design for controlling the BR player.
	The customer asked to add 6 sports channels on the Home Theater main page.
11.03.2012	Connected the CV5 panel, uploaded the design.
	Uploaded the edited design on iPad, added 6 sports channels on the Home Theater main page, added the page of waiting for turning the projector ON/OFF to the project.
	The installers haven’t solder the contacts.
	Uploaded the module for the receiver with radio.
	Checked work of Home Theater (on/off), fixed the up/down movements of the screen.
	Checked control of BR-Audio
	Add the change of the acoustic model on the receiver control page.
	Checked radio control on the receiver.
	Error: when pressing on the empty area of the receiver control page the receiver turns off. It turned out the invisible button with the code for turning the receiver off was not deleted.

In the example above you can see indicated dates and events. Problems you need to solve or pay attention to are marked blue. You can add other items to your journal, for example, time of starting/finishing tasks (to understand how much time you need to complete them). You can add color marking, which will indicate important events in the project. Anyway, it’s only up to you how detailed your journal will be and what it will look like.

Standardization of the Code Format. Each programmer has his own habits of naming variables and procedures and writing the code. It is quite common to see code varying from object to another. The majority of Smart Home programmers are skeptical about standardizing their code. Using a standard way to code, will increase the readability of the code, i.e. you will not need to see through the context to understand the functionality, thus saving you time. It will allow several programmers to work more effectively on the same code.
Example of the code fragment for the AMX controller:

define_function ot(char i, integer a, integer val)

{

    char t;

    if(i == 0)

    {          for(t =1; t <= 64; t++)

                    send_string 5001:1:0,"'d:',itoa(t),':',itoa(a),':',itoa(val)";

    } else { send_string 5001:1:0,"'d:',itoa(i),':',itoa(a),':',itoa(val)"; }

}

This code has several flaws:

1. No description of the function.
2. You cannot understand what the function does by its name.
3. There are some «magic» numbers.
4. Incoming properties of the function are not descriptive.
5. The initial code is badly formatted and is difficult to read.

The same code for the AMX controller can be presented differently when using a standardized approach:

/**

    Sending data

    on the input           :          in_cPoint          - a device point (0 – send to all device points)

                                           in_iAddress      - the device address in the point

                                           in_cValue         - a value for setting up

    on the output        :           *

    note     :           у in_cPoint the tolerance range of in_cPoint is not verified

*/

define_function SetValue(char in_cPoint, integer in_iAddress, char in_cValue)

{

    char i;

    if(in_cPoint == 0)

    {

                // Sending data to all device points

                for(i = 1; i <= 64; i++)

                    send_string dvAMX_RS232_PORT_1, "'d:',itoa(i),':',itoa(in_iAddress),':',itoa(in_cValue)";

    } else

    {

                // Sending data to the indicated point

                send_string dvAMX_RS232_PORT_1, "'d:',itoa(in_cPoint),':',itoa(in_iAddress),':',itoa(in_cValue)";

    }

}

As you can see this code is easier to understand. Based on my own experience I can say that time spent on understanding the code written with and without the standard differs considerably. Besides, if you work in a team, it will be very difficult to adjoin parts of the code or use the existing code without agreeing on some standard. The crucial role in writing the code belongs to comments: the more comments you write, the better – so don’t be lazy. When you return to the code you will thank yourself for not being lazy. Moreover, by creating the comments you explain to yourself why you have coded certain task to operate in a particular way.

Utilizing the Code. The very effective measure for speeding up the process of development of new objects is utilizing the codes you have, i.e. using the modules, functions and procedures developed previously by you or other programmers. As a rule the majority of installation companies work with a limited range of equipment. That is why it makes a lot of sense to create projects, write and set up modules for most frequently used devices. Besides, a lot of devices use similar logics in their work. It can be different only by the number of commands and/or their.

Using the Debug Window. One of the essential things in the process of writing a code is its debugging. You can use the following instruction for debugging the program of the AMX controller:

// Debug information
if(m_bDebug)
   send_string 0, "''debug information'";

As you might notice there is the m_bDebug flag. When you set up the flag to the non-zero value you activate the mode of outputting the debug messages. Writing in 0 port of the AMX controller outputs information in the debug window which it very convenient. You can also implement the more advanced system of outputting information and create several debug levels. For example:

0 - no debugging
1 - output of errors
2 - output of errors and warnings
3 - output of errors, warnings and other messages

In this case it looks as follows:

// Output of errors
if(m_cDebugLevel >= DEBUG_LEVEL1)
   send_string 0, "'::error::'";

// Output of warnings
if(m_cDebugLevel >= DEBUG_LEVEL2)
   send_string 0, "'::warning::'";

// Output of other messages
if(m_cDebugLevel >= DEBUG_LEVEL3)
   send_string 0, "'::other::'";

Use of debugging via the diagnostic window of the AMX controller is a very convenient approach which helps to monitor the program behavior and trap the emergency situations.

Storing of Old Versions. One of the critical moments in programming is saving the initial code on different stages of its development. Storing of old versions might seem silly but it’s only at a casual glance. Sometimes after several alterations the functions which worked in the previous version are missing. So if you haven’t saved the previous version it will be difficult to understand what went wrong. Besides, if you haven’t had enough time to finish something and your clients need to have something it is easier to leave the previous version working. I use two ways for storing old versions:

1. Archive. In the end of a working day or after finishing some project stage you should archive your data. To make it more convenient I create a bat file for each particular project. This bat file will archive all important files indicating their name, date and time. And later you are able to see what was done in this or that version.
2. Use of some system for managing different versions, for example SVN. In this case the source files will be not only on your PC but also in some network storage. The main advantage of this method is the possibility of synchronizing the files from anywhere you are, if you have access to SVN. Besides, SVN stores all versions, remembers when and what files were altered, who did that, etc. I’m sure you’ll agree that it’s very convenient. But there are also disadvantages: you need to set up the SVN server and always be online.

And one more important thing.

Work place. The majority of AMX programmers write programs right on their objects. But it’s very inconvenient: sometimes there is no chair, table or even the Internet. Of course you can bring all these things with you but it won’t substitute a comfortable work place. My advice is to do all the work in the office, in the conditions comfortable for you. You can create a copy of the future AMX system and set up everything in your office. Then spell out the order for testing of the AMX system. It will help you not to overlook some important functions of Smart Home.

I hope you will find my experience useful and it will help you in creation of reliable automation systems. In my future articles I will tell you how to program various units of AMX modules: sequence of sending messages to controlled devices, processing of data received from controlled devices, etc.