Web Control of Modtronix IOR5E Relays

The Modtronix IOR5E is an Input Output Relay board with enclosue designed to contain a PIC based SBC such as the. Modtronix SBC65EC or SBC68EC. It is about the size of three stacked CD jewel cases and draws only a few dozen milli-amps of power.

The Modtronix IOR5E

This cute little piece of boxed hardware comes with five small-applicance power grade relays as well as a dozen programmable panel LEDs, digital and analog inputs, and digital outputs, all neatly accessible via tidy pluggable screw terminals. And did I mention the ethernet port complete with built-in web server and DHCP support? The board can be fully programmed using free software. All in all, a pretty nifty (and not very expensive) piece of universally useful hardware.

That's the good news.

Unfortunately --out of the box-- this little gadget sadly does not know how to access its usable hardware assets (the ones connected to the handy screw terminals). As mentioned, the programming tool software was free (you need that software in order to teach the box how to do something useful), but in order to run that free software, you need to be operating a computer running a certain Microsoft operating system. Then you need to download and install a bunch of software (which needs some post- install tweaking), and finally there is some interesting C-subset programming for the board itself. Somewhere along the way, you need to reconfigure your network interface and then remember to unconfigure it. It all sort of works, but only if you know to read and follow ALL of the instructions. This turns the whole experience into a bit of an RTFM scavenger hunt reminiscent of an early 80's text based computer game, where in order to get the Amulet or Yendor you need to defeat the Great Ogre using a particular sword found at the end of some secret passage that is only accesible though the castle's fireplace on a fullmoon after sunset. You get the idea.

It's all do-able. All it takes is about a long weekend with nothing to do, (less if you know how to read instructions, even less, hopefully, if you follow the hints below), a windows laptop, a hub, an internet connection, and a certain insane committment to run your lawn sprinkler off your crontab.

Compiling and Loading your code onto the Modtronix SBC

Before emparking on tweaking and compiling the code yourself, let me offer you my precompiled version, with working LEDs and web access to the five relays. This configuration is hard-coded to IP 192.168.1.150 (because in a serious power outage, the box will come up long before my internal DHCP server). You will still need to download and install te Modtronix network boot loader and load the new code (including messing with your workstation's IP address) but you will be able to bypass most of the build instructions.

If you're a puritan, or paranoid, or bored, or curious, or that IP does not work for you, or you want to be able to do more than just turn on the relays, then read on to learn how to patch the Modtronix source to give you access to the relays and more. Hopefully, the information and steps outlined below will make things easier for you. If you see something wrong or missing these instructions, please let me know.

Here is goes:

1. Throwing caution to the wind, rip open the courier package and gleefully assemble the little box before reading any documentation (but following customary rules of electrostatic hygiene). Feel free to ignore the instructions and to power it up and to bask in the glow of the blinking LED. The built-up anticipation of making it sing for you will hopefully help carry you through what comes next. You'll need it.
2. Download and unzip/install onto your "favourite" MS Windows box:
   • The The Modtronix Network Bootloader java based windows application
   • Microhcip Technology Inc'sMPLAB C18 C Compiler and IDE
   • The Modtronix SBC68EC Web Server source code

3. Following the instructions found on the modtronix web site configure your IDE to use the C compiler you just downloaded. The default tool paths are wrong, and so is the default target processor. If you get this wrong, the build will fail with some more or less cryptic message.
4. Following more instructions found on the modtronix web site, start hacking the webserver source code you downloaded previously. You will want to snarf the setLatch595 function from the sample code posted on the modtronix support forum and then add some relay specific code to mxwebsrvr.c to set the relay outputs and to httpexec.c to trigger that via http parameters. In case you are curious, not only are the LEDs on the panel not actually hooked up to the relays (presumably so you can use them for some other purpose), their order is also not what you would expect by looking at the panel, thus the weirdness in the C code.
5. You will also want to fix that brilliant default network configuration to have your box use DHCP or at least to a less braindead default static IP address, like one that does NOT clash with your internal firewall settings.
6. Build your project. If you get a happy "SUCCESS" message at the end, then you're ready for loading it onto your box. If not, then you probably skipped the IDE tool configuration step. (assuming no errors in your C source modifications)

Before trying to upload your code, you need to know that the product design elves at Modtronix somehow think that 10.1.0.1 or 192.168.0.1 are not only good for some dyslexic fun but are also good default address for hardware in today's world. That practical joke is followed up on their web site by an offer to sell and courier you a special serial cable -- from Australia -- using which you could correct this small detail ... if only your 2005 vintage laptop had a serial port. (Hey guys, how about DHCP out of the box with something like 192.168.1.101 as plan B?)

1. Instead of ordering the cable, plug your windows box into the same ethernet hub or switch as your new little box and configure your workstation's ethernet interface to use a static IP like 10.1.0.2. You will only need to jump through this hoop this one time.
2. Launch the Modtronix network boot loader you installed previously and ask it to connect
3. Power up your new little box
4. In the network booot loader java winsows app, browse to the .hex file you just automagically created by compiling your project (hint: it's in the same place as the source code) and tell it to send that to your box
5. Watch the new little box load its new software, then reboot and do your bidding ... and become unaccessible over the network (if you followed these instructions, then the new firmware will have told the box to be something better than 10.1.0.1 which means it will not longer be able to talk to your workstation)
6. Re-configure your windows box to use whatever IP you were using before

You should now be able to talk to your new toy using your web browser at whatever IP address you configured. Next time you want upload the software, you should be able to do so just by bringing up the bootloader on the PC and then power cycling the little box (there is also a way to kick it into a reboot over the web).

If you're not, consider waiting for a few minutes for your network to digest what just happened. I noticed twice during my installing the box that it took a few reboots and/or minutes for the network to figure out that the box had moved. However, once that settled down, the box now works very reliably.

The IOR5E Front Panel

By hitting the web server with the right query parameters, you should now be able to turn on the relays and corresponding LED panel lights.

The "Other" IOR5E Front Panel

If you get lost, know that you are not alone and that the modtronix messages boards hold more clues.

The Mythical Crontab Sprinkler

If you're like me, then your average sprinkler controller is lacking in two fundamental ways:

1. I cannot control it from where I am (wherever that may be)
2. My software cannot use it to control watering schedules

Both these problems can be fixed simply by adding a network interface. Since there are no hackable affordable sprinklers with ethernet ports, we'll just have to use a hackable remote IO box such as the IOR5E as the business end of a sprinkler controller.

The problem is, however, that any practical implementation of a controller network interface must take into account the considerable damage that can be caused by a poor implementation (or even a good one under conspiring circumstances):

This is why the code offered here has one important safety feature: the relays are not just turned on. They are only turned on for a certain amount of time (They also, of course, turn off every time the box is reset.) This means that if some software entity decides to turn on the sprinklers and then dies (or your network goes away, or your system disk dies), the water will not be running forever. This is not foolproof, but it is probably a much more conservative way to flood your neighbour's basement :-)

The code does this by adding a new parameter to the Modtronix web server:

Hexmask is a bit mask identifying which relays are to be turned on. "01" identifies the first relay only, and "1f" identifies all relays. duration indicates the number of seconds for which those relays should be turned on.

http://yourbox/IOVAL.CGI?z01=10	turn on relay #0 for 10 seconds; do not change anything else
http://yourbox/IOVAL.CGI?z02=10	turn on relay #1 for 10 seconds; do not change anything else
http://yourbox/IOVAL.CGI?z1f=10	turn on all relays for 10 seconds
http://yourbox/IOVAL.CGI?z1f=0	turn off all relays
http://yourbox/IOVAL.CGI?z03=1800&z04=600&z19=0	turn on relay #2 for half an hour, relay #3 for 10 minues, and turn off all other relays
http://yourbox/IOVAL.CGI?z1f=0&z03=1800&z04=600	turn on relay #2 for half an hour, relay #3 for 10 minues, and turn off all other relays

Now, if only my lawnmower had WIFI...

IOR5E Network Sprinkler Controller Installed

Note that you can turn relays on and off separately withoug affecting each other's count-down. After the respective specified times, the relays will turn off and remain off until receiving new instructions. Anything smarter than this (like turning on sprinklers at midnight on a follmoon, or if a certain motion sensor goes off) you need to do that on another computer, like your always-up file server or desk top, for instance. This last bit actually not that hard. All you need is a ten line CShell script and crontab entry to go with it.

Modtronix Wishlist

Since I am considering getting more units like this eventually (five sprinkler zones done, twenty sprinklers and a few dozen motion lights left to go), here is what I would like to see in the revision of this product:

1. A default address that is likely to work with most peoples internal network settings. Much of the world now has interal DHCP, a router at 192.168.1.1, and a network mask of 255.255.225.0.
2. A way to use the box that does not require me to customize C code. How about providing a downloadable .hex which exposes the IOR5E hardware to a primitive UDP protocol or at least makes its relays, inputs, and outputs fully accessible via HTTP somehow?
3. For those wanting to hack C source code, at least have clean extension points so that users can copy / paste / share / combine their source in small clean modular chunks instead of having to merge sources at such a low level. It does not need to be this messy.
4. It would be nice if you could figure out a way to allow C programming of the box from machines other than windows work stations.

Similar Hardware

What I am looking for (and I know I am not alone) is this:

1. inexpensive
2. low power
3. reliable
4. ethernet
5. sealed box with screw terminals
6. six or more low voltage relays and/or opto-isolated high impedance digital inputs
7. basically works out of the box with all available hardware accessible via simple open network API (relays: must be able to shut off automatically after a certain time, inputs: change must trigger alert message)
8. DHCP/Bootp support
9. programmable from a Linux/FreeBSD system ten years from now

If you know of similar hardware, please let me know.

License

These instructions and related code snipets were developed by Helmut Hissen and Zeebar Technology 2006. Feel free to use this information for your own private personal enjoyment. For all other uses, contact the author: helmut@zeebar.com.