Sprinkler Controller -- V1.0.2 (released June 7, 2006) Baud Rate is fixed at 9600 baud, 8 data bits, 1 stop bit, no parity, no flow control. Commands are sent in the format of @xx... there the first two characters are a command and the following characters, if any, are parameters. The command is terminated with a . Any character received before the @ is ignored and anytime an @ is received, any currently incompletely command is discarded (so you can get half way through a command, realize there is an error and just type @ and the correct command). All commands will eventually send an @F0 or @F1 back. However, depending on the command and it's affects on the controller/valves, there may be one or more other reports sent before the @F0 or @F1. You should allow for this and hold off sending a command until you get a @F0/F1 response back (though technically you can as there is a fair sized buffer) or a timeout expires (at least 10 seconds). In the case of a timeout, it's probably a good idea to reset the controller (via @FF) to prevent sprinkler run-away. NOTE ON PACING: The ideal way of not over-running the controller is to send a command wand wait until you receive an @F0 or @F1 response back. However, if you are not able to or interested in reading the reports back from the commands, you can safely send each command with a 1/10th second gap/delay between each command. This is likely way more than is needed, but will pretty much guarantee no command will be lost. All values are in hex and all hex alpha characters must be in upper case (i.e. A,B,C,D,E and F are valid, a,b,c,d,e and f are not). All commands and responses are multiples of 2 hex characters (plus the leadin character, @). All commands and responses are terminated with a single CR (ASCII 13). There are 8 queues that can be used, addressed 00 through 07 (allowing up to 7 valves to be open at one time). There are 27 valves available, addressed 00 through 1A. The controller can accept up to 48 queued valve requests at once. Those 48 entries are shared amongst the queues, so this is a global limit. You could have 6 entries in each of 8 queues, 30 entries in queue #00, 10 in queue #04 and 2 in #07 (queue #s in this example are arbitrary) or all 48 in a single queue. @01QQVVMM[II] Add Valve VV to queue QQ to be opened for MM minutes. VV is the valve, in hex, to open from 00 to 1A (0-26) or special values F0 or F1. Valve F0 is special in that it is not really a valve, but will occupy space and time in the queue. This allows you to pause a queue for MM minutes (perhaps in a misting arrangement). Valve F1 is also special in that it will stop the queue until another queue is empty. The other queue is passed as the # of minutes. If the queue passed in the minutes field is invalid or is the same as QQ, this command is ignored and not added to the queue. Any valve above 1A (other than F0 & F1) is invalid and the command is ignored. The first valve is 00. QQ is the queue to add to. Valid values are 00-07. Any other value is invalid and the command is rejected. MM is the minutes to open the valve for in hex. 00 is valid, though the valve will not open and when this entry in the queue gets to the head of the queue, it will immediatly be discarded without ever opening the valve. FF is 255 minutes. II is optional and is the position to insert this valve queue in the queue. If not supplied, the entry is appened to the queue. If supplied, but the number is higher than the number of queue entries, it just appends the entry as if II were not even included. If II is 00 and the queue is running and the valv at the current head of the queue is open, it will be closed and this installed. The former head of the queue is moved to index 1 and when this entry is complete, it will run out the remainder of its time (if the valve was originally queued for 10 minutes and 3 minutes in, a new valve was queued at the head, the current valve would be closed, pushed to the #1 position and when the newly added entry completed, the remaining 7 minutes of the vales run would complete). NOTE: If a valve is added to more than one queue and for any reason two (or more) queues are "opening" that valve at the same time, the valve will stay open for the duration of each queued open time. So, if valve #00 is queued to queue #0 for 2 minutes and queue #1 for 3 minutes and both queue #0 and queue #1 have that valve as the top of their queue (i.e. the open valve), the valve will be open for 5 minutes total. @10QQ Start/Resume queue QQ if it was paused (ignore if not paused). QQ is the queue number, 00-07. If the queue was paused before while a valve was open, that valve will re-open and the minutes remaining timer for it will resume ticking. NOTE: You can pass queue FF to start/resume all queues at the same time NOTE: At powerup, all queues are started and ready to open valves. @11QQ Pause queue QQ. Any valve associated with the queue will be closed and it's "time remaining" counter frozen. No additional valves in the queue will start either. QQ is the queue number, 00-07. NOTE: You can pass queue FF to pause all queues at the same time @12QQ Clear Queue QQ. All entries in the queue are removed/discarded and if there was any valve opened, it's closed. QQ is the queue, 00-07. NOTE: You can pass queue FF to clear all queues at once @13QQII Remove item at index II in queue QQ. If II is beyond the end of the queue, the command is ignored. If II is 00 and the valve is opened, it is first closed, then the entry discarded and the queue moves on to the next entry. QQ is the queue, 00-07. @14QQIIDD Move queue entry II in queue QQ to index DD. If DD is beyond the end of the queue, then the item is moved to the end of the queue. If II is not valid (or QQ), then the command is ignored. If II is 00 and the valve is opened, it's closed and moved to the DD index. It's minutes remaining will be left where it was when closed (i.e. it's not reset back it's start -- if entry 00 for valve 3 had 6 minutes queued and was 2 minutes into it when moved, when that entry again gets to the head, it will then run out it's remaining 4 minutes. @15QQIIMM Change the time remaining to MM minutes for item at index II in queue QQ. MM is 00-FF where 00 is no minutes and FF is 255 minutes. II is the index into the queue where 00 is the head of the queue. QQ is the queue, 00-07. If the queue or index is invalid, the command is is ignored. If you change the time remaining to 00 for the head of the queue, the valve will immediatly close and the next queue entry will be processed. @E0 Report the version of the firmware via an @80 report @E1 Report the days/hours/minutes/seconds since the controller was last powered up and/or reset/rebooted via an @81 report. @E2 Report the status of the pump via an @82 report @E3VV Report the state of valve VV. No report is sent if the valve is an invalid number. Otherwise, the current status of the valve (open/closed, queued/not queued, etc) is returned in an @83 response. You can send a valve of FF to have all valves reported back, in order. @E4QQ Report the status of queue QQ. QQ is 00-07. Status will be returned in an @84 NOTE: You can pass queue FF to report on the status of all queues @E5QQII Send a status report (@85) for item II in queue QQ. QQ must be a valid queue (00-07 only) and II is a valid index into the queue. If either is not valid, no report will be issued. @E6QQ Send a complete queue inventory report (@86) for queue QQ. QQ must be a valid queue only (00-07 only). NOTE: You can pass queue FF to report on the inventories of all queues @EF Send controller parameter settings. This will result in an @8F reply that will include the current delay between valve opening, the pump cycle delay and the max valve open time. @F0SS Set the delay between valve openings. If two valves need to open within SS seconds of each other, the first will open and the second will open after SS seconds. In short, if SS is 03, then even if all 8 queues demand to open valves at the same time, they'll be a 3 second delay after each valve opens before the next (so in the case where all 8 queues wanted to open a valve at the same time and SS was 03, it would take 24 seconds before all 8 valves were opened). This is designed to minimize the load on the valve transformer and to allow some settling time. The default is 03 and it can be set from 00 to FF (255) seconds This value is preserved across powerfail and reboots, so once set, should not need to be set again. @F1SS Set the delay time after the pump stops before it can start again. If the pump starts and within SS seconds there is a new request for a valve that would need the pump, that request is held until SS seconds has elapsed. This hold time is not counted against the valve open time, so after the pump is OK to resume, the valve will stay open the full amount of time it was supposed to. This is designed to reduce stress on the pump. Some pumps need a recovery period after being turned off before they can be turned on again. The default is 120 seconds (78 hex) and can be set from 00 to FF (255). This value is preserved across powerfail and reboots, so once set, should not need to be set again. @F2MM Set the maximum time that any valve can be open to MM minutes. This is part of the valve supervisor -- a completely seperate code segment that is used to prevent a bug in the firmware from leaving a valve open indefinetly. Normally, if there were a bug, the watchdog timer would likely catch and reboot the board. However, it could be possible that some other logic flaw allows the wathdgo to be serviced, but the valves left open. This is here to compensate for that. Any request to queue a valve will have it's time value limited by this value. And if for any reason, a valve stays open more than this many minutes, the board will reboot. The default is 90 minutes (5A in hex) and it can be set to any value from 05 to FF (255 minutes). Values less than 5 minutes are ignored (no change to the previously set time limit occurs). This value is preserved across powerfail and reboots, so once set, should not need to be set again. @FF Reset/Reinitialize the board. All queues are cleared, valves are closed and pump stopped. After the @F0 confirmation message, you should wait until you hear the board announce it's re-initialization with a @00 report before sending any reports. This does reset the "uptime" for the controller (the @8F report, after this, would be @8F0000000000). Response Codes (sent for each command issued): @F0 - Last Command Accepted OK @F1 - Last Command not accepted (error in command, queue full) Status Reports (sent in response to a status request command): @80MMmmPP Reports the version of the firmware where the first two digits are the major version, next two are minor version and last two are patch level. Sent in response to @E0 @81DDDDHHMMSS Reports the number of days, hours, minutes and seconds the controller has been running (since powerup or last reset/reboot). Days is returned as a 16 bit value (4 hex numbers) allowing the controller to be running a bit shy of 180 years before it rolls over. Hours is the number of hours in the current day (00-17 (i.e. 24 hours tops)), minutes is the number of minutes in the current hour (00-3C (i.e. 60 minutes tops) and seconds is the number of seconds in the current minute, 00-3C. Sent as a response to @E1 @82PP Pump Status report. PP is a bitmap of the pump status. This is sent in response to a query for the pumps state (via @E2) Bit Description 0 1 = Pump On/Active, 0 = Pump Off 1-7 Reserved @83VVSS Valve Status Report. This is the same as a valve trigger report, but indicates that the value was requested (via @E3) vs the result of a change in state. VV is the valve number. SS is the state of the valve. It's a bit map decoded as thus Bit Description 0 1 = Valve Open Right now, 0 = Valve Closed 1-7 Reserved @84QQSSCC Queue status report. QQ is the queue number, 00-07. SS is a bit map of the queue state (defined below). CC is the number of entries in the queue, 00-FF (though realisitcally, that will never be more than 48 decimal). Sent in response to @E4 Bit Description 0 1 = Queue Running/Active, 0 = Queue Paused/Stopped 1-7 Reserved @85QQIISSVVMM Queue item status report. Describes an item in the queue and what it's state is. QQ is the queue, 00-07. II is the index of this entry in the queue. SS is a bit map describing this entry. VV is the valve number and MM is the minutes remaining. Sent in response to @E5 Bit Description 0 1 = Valve Open, 0 = Valve Closed 1-5 Reserved 6&7 Reserved for Trigger action. Meaning as follows 00 - Reserved 01 - This item just added to the queue 10 - This item just removed from the queue 11 - This item was just reordered in the queue NOTE: It is possible for entry 00 (head of the queue) to not have the valve open if the queue is paused. NOTE: Valve status is actual valve status. That could mean that if a valve is currently open in some other queue, this might be set even if this is not the head entry in the queue (i.e. II is not 00). NOTE: While valve status is included, changes in it alone will not cause an @95 trigger report. @86QQSSCCVVMMvvmmVVMMvvmm.... Queue inventory report. It starts out as a queue status report and the first 6 characters has the same meaning as an @84 report. Following the queue status is each valve in the queue (VV or vv) and the minutes remaining for that valve (MM or mm). So the exact length of the report will vary, though the number of VVMM pairs will exactly match the count CC. Sent in response to @E6 @8FVVPPOO Reports the current board configuration information. These values can be changed using @Fx commands. VV is the number of SECONDS delay between opening valves. This prevents all active valves (up to 8, 1 for each queue) slamming open at the same time and overloading the valve transformer PP is the number of SECONDS delay after the pump shuts off before it can restart. This protects the pump from short-cycle damage which can be a problem for some pumps OO is the number of MINUTES a valve can be opened after which the valve supervisor decides the board is failed and reboots. This is a fail safe that prevents a valve from being left open indefinetly in the event of a controller firmware bug. Triggers (sent asynchronously in response to a change in status): @90MMmmPP Board has been (re)initialized. You'll get this 1 second after power up or 1 second after any catastrophic failure has caused the board to reset. When you receive this, you can confidently know that 1) there are no open valves, 2) the pump is not running and 3) the queues are all started but are empty. If you receive this in any sort of control program, you should immediately reset/clear all cached board info/status. MMmmPP are the same as an @80 report -- the major, minor and patch version of the firmware. @92PP Pump Trigger report. Same format as the pump status report, but sent whenever there is a change in pump status (@82). @93VVSS Valve trigger report. Sent when there is a change in the state of the valve (being opened, being closed, being in any queue or removed entirely from one previously in -- basically, a change in anything reported in SS). This has the exact same format and meaning as the @83 valve status report. @94QQSSCC Queue Trigger report. Same format as the queue status report (@84), but sent whenever the queue changes (state or number of queued items) @95QQIISSVVMM Queue item trigger report. Sent when any aspect of a queue item has changed. That includes the item being added, item being removed, the state of the items valve changing or the number of minutes the item is queued for changing. This last fact means when an entry is at the head of the queue and the valve is open/queue is running, you'll get a report once a minute as the time remaining is reduced. In terms of order, a change in valve status (open/close) will result in a @93 trigger, then posibly a @92 trigger, then the @95 trigger, though you should allow for them coming in any order. Meaning and format of this trigger is the same as an @85 status report.