Data Formats for Communication Between Android App and precipiSTATION
Below is perhaps too exhaustive detail on the message content between the Android app and precipiSTATION as it verges on a datasheet but here it is anyway.
Particle function: fetchData(String x)
Particle function saveData(String x)
Particle Function runOnce(String x)
Particle function setTwitter(String x)
Particle variable stnList
A String, like "Palm Tree,Palm Ring,Under Front Deck,Fireplace Bed,Driveway Around Palm,Back Garden,Back Yard,Back Plants,Driveway Right Side,Driveway Left Side,Studio Front and Side,Oleander,Orchard Front,Orchard Back,Succelents and Cactus,Mailbox Area,|" (with no quotes) is returned. 16 station names each followed by commas, ended by a "|"
Particle variable pgmList
A String like "Create a New Program,Palm Tree,6AM Mist,Afternoon Mist,Orchard and Garden,Driveway,Late Night Mist,|" (with no quotes) is returned. Names of all stored programs, each followed by commas, end by a "|" (including "Create new Program" for use by Android app as first selection item in its program list picker).
Particle variable pgmData
A String like "04,14,15,127,20,0,0,0,20,0,0,20,0,0,0,0,0,0,0,0," (with no quotes) is returned. Indicates program number (04), start time hour (14 hundred military time); start time minute 15 (translating hours and minutes ... 2:15PM); followed by station run time for each of the 16 stations.
Particle variable statusData
A warning ... this one is the most arcane of the data formats. It was added at the end of the project, and I am sure you will see it was obviously made up on the fly. There are 4 segments to the message, each separated by the "|" character. An example is below:
2000,16,4,0,0,0,600,44,2,0,644,0,1415,60,3,0,0,0,1722,325,4,0,2217,30,|1,2115,14,15|0|4,0,2200,045,0,0,3|
The first section of this String provides data on regularly scheduled programs - the Sting above shows 4 programs. 6 items of information are provided for each - the start time in military time; the duration of the program; the run time status (1 = running, 2 equals already ran, 3 = scheduled later today, 4 = not scheduled today); if running now, the station that is running; if running now, the station start time; if running now, the station time duration of currently running station. The first program is always program 2, and in this example, starts at 20:00 military time, has a duration of 16 minutes, and its status is "not scheduled today" (indicated by the number 4), and is followed by 3 zeros since a station is not running. If you skip forward to 600 .... this is program 3, and it starts at 06:00 hours, runs for 44 minutes, and was already run today (indicated by 2), and its last station ended at 06:44. This segment ends with a "|" which is used by Android app to recognize the end of this data segment.
The second segment of this String holds status on "Run Station Once". If a 9 is shown (randomly selected number), there are no "Run Station Once" items. If there is a "Run Station Once" that ran, is running or is scheduled, 4 items of information are provided, including station status (1= running, 2 = ran, 3 = scheduled); station start time in military time; station number, and run time duration. This section is ended by a "|". In above String, station 14 is running now (1), started at 9:15PM, and will run for 15 minutes(I should reorder these someday I suppose).
The next segment indicates if a sprinkler test is under way. A "0" indicates no test is in progress, Any number from 1-16 indicates that particular station is currently running its 1 minute test. This segment of the string ends with a "|".
The last segment of statusData contains information on "Run Program Once" status". If it is a 9 (randomly selected number), there is no "Run Program Now" events that ran, are running, or are scheduled. If there are "Run Program Now" cases, 7 items of data are sent, including program number; station number now running, program start time in military time; program duration in minutes; start time of currently running station; run time duration for currently running station in minutes; and station status (1= running, 2 = ran, 3 = scheduled); In the above example, program 3 (the first 4), is scheduled to run (the 3 at the end), will start at 10:00 PM (the 2200), and run for 45 minutes. The 3 other fields are 0 because no station is running (second item), so there is no start time (5th item) and no run time for that station (6th item).
Next time I define String formats, I will certainly do it in a less ad hoc way!
Particle Variable TwitOnOff
This variable, will be one of 10, 20, 30 or 11, 21, 31. The second digit shows sprinkler status (0 = off/disabled, 1 = enabled). The first diit indicates if Tweets are disabled (3); program start and end only tweeting is enabled(1); program start, stations starts, and program end tweeting is enabled.
Particle Variables Debug_0, Debug_1, Debug_2, now, and pgmTotal
These variables are not used by the Android app. They were used in debugging firmware using Atomiot.
Below is perhaps too exhaustive detail on the message content between the Android app and precipiSTATION as it verges on a datasheet but here it is anyway.
Particle function: fetchData(String x)
- "P" - Just the letter "P" is sent to inform the Particle function to assemble a CSV array in Particle variable pgmList[] that lists all the currently stored program names in ASCII
- "S" - Just the letter "S" is sent to inform the Particle function to assemble a CSV array in Particle variable stnList[] that lists all the currently stored program names in ASCII.
- Dxx - Sends D01 to D16, with the xx being the program of interest. Informs the Particle function to assemble a CSV array of program run time data for program xx in variable pgmData[].
- "Z" - Just the letter "Z" is sent to inform the Particle function to assemble a CSV array in Particle variable statusData[] that lists all the current sprinkler status, history, etc. for the current day.
Particle function saveData(String x)
- "Pxxnameofprogram," - String with "P" at start, followed by program number in 2 characters (02 - 16), followed by ASCII letter of program name. Example - "P06Back Yard," means program number 5 is named "Back Yard".
- "Sxxnameofstation" - String with "S" at start, followed by station number in 2 characters (01 - 16), followed by ASCII letter of program name. Example - "S11Palm Tree," means station number 11 is named "Palm Tree".
- "Dxx,hh,mm,ddd,time,time,time,time,time,time,time,time,time,time,time,time,time,time,time," A "D" to inform Particle function this is program data message. "hh = start time in military time; "mm" equals start time minute; days is three characters from 000 to 255 indicating days the program should run; "time" is the run time duration for each of stations 1-16. Example .... D09,23,50,127,20,0,0,0,0,0,20,0,0,0,0,0,0,0,0,0, ... means program 9 should start at 11:30 PM, running Station 1 for 20 minutes, followed by station 7 for 20 minutes. It should run every day (127).
- "O" - Just the letter "O". Shut off the sprinkler and disable further operation
- "A" - Just the letter "A" - Enable sprinkler operation according to regularly scheduled operation
- "Rxx" - The letter "R" followed by 2 characters indicating the program that is to be removed/deleted.
Particle Function runOnce(String x)
- "Pxxhhmm" - the letter "P" to indicate "Run Program Once" message, followed by 2 characters from 02 to 16 to show program number (program 1 is reserved for "Create a new Program" in Android app so in a convoluted way, program 2 is actually the first actual program); followed by start time in military format. Example P041215 indicates run program 3 once, at 12:15PM.
- "Sxxhhmmddd" - the letter "S" to indicate "Run Station Once" message, followed by 2 characters from 01 to 16 to show station number, followed by start time in military format, followed by 3 character run time duration. Example S120100160, indicates run station 12 once, at 1:00AM for 160 minutes.
- "T" - Just the letter "T" informs precipiSTATION to run a Sprinkler Test (run each station for 1 minute).
Particle function setTwitter(String x)
- "x" is sent, where x is the character 1, 2, or 3. Tweets disabled = 3; Tweet program start and program end only = 2; Tweet start of program, start of each station, and program end = 2;
Particle variable stnList
A String, like "Palm Tree,Palm Ring,Under Front Deck,Fireplace Bed,Driveway Around Palm,Back Garden,Back Yard,Back Plants,Driveway Right Side,Driveway Left Side,Studio Front and Side,Oleander,Orchard Front,Orchard Back,Succelents and Cactus,Mailbox Area,|" (with no quotes) is returned. 16 station names each followed by commas, ended by a "|"
Particle variable pgmList
A String like "Create a New Program,Palm Tree,6AM Mist,Afternoon Mist,Orchard and Garden,Driveway,Late Night Mist,|" (with no quotes) is returned. Names of all stored programs, each followed by commas, end by a "|" (including "Create new Program" for use by Android app as first selection item in its program list picker).
Particle variable pgmData
A String like "04,14,15,127,20,0,0,0,20,0,0,20,0,0,0,0,0,0,0,0," (with no quotes) is returned. Indicates program number (04), start time hour (14 hundred military time); start time minute 15 (translating hours and minutes ... 2:15PM); followed by station run time for each of the 16 stations.
Particle variable statusData
A warning ... this one is the most arcane of the data formats. It was added at the end of the project, and I am sure you will see it was obviously made up on the fly. There are 4 segments to the message, each separated by the "|" character. An example is below:
2000,16,4,0,0,0,600,44,2,0,644,0,1415,60,3,0,0,0,1722,325,4,0,2217,30,|1,2115,14,15|0|4,0,2200,045,0,0,3|
The first section of this String provides data on regularly scheduled programs - the Sting above shows 4 programs. 6 items of information are provided for each - the start time in military time; the duration of the program; the run time status (1 = running, 2 equals already ran, 3 = scheduled later today, 4 = not scheduled today); if running now, the station that is running; if running now, the station start time; if running now, the station time duration of currently running station. The first program is always program 2, and in this example, starts at 20:00 military time, has a duration of 16 minutes, and its status is "not scheduled today" (indicated by the number 4), and is followed by 3 zeros since a station is not running. If you skip forward to 600 .... this is program 3, and it starts at 06:00 hours, runs for 44 minutes, and was already run today (indicated by 2), and its last station ended at 06:44. This segment ends with a "|" which is used by Android app to recognize the end of this data segment.
The second segment of this String holds status on "Run Station Once". If a 9 is shown (randomly selected number), there are no "Run Station Once" items. If there is a "Run Station Once" that ran, is running or is scheduled, 4 items of information are provided, including station status (1= running, 2 = ran, 3 = scheduled); station start time in military time; station number, and run time duration. This section is ended by a "|". In above String, station 14 is running now (1), started at 9:15PM, and will run for 15 minutes(I should reorder these someday I suppose).
The next segment indicates if a sprinkler test is under way. A "0" indicates no test is in progress, Any number from 1-16 indicates that particular station is currently running its 1 minute test. This segment of the string ends with a "|".
The last segment of statusData contains information on "Run Program Once" status". If it is a 9 (randomly selected number), there is no "Run Program Now" events that ran, are running, or are scheduled. If there are "Run Program Now" cases, 7 items of data are sent, including program number; station number now running, program start time in military time; program duration in minutes; start time of currently running station; run time duration for currently running station in minutes; and station status (1= running, 2 = ran, 3 = scheduled); In the above example, program 3 (the first 4), is scheduled to run (the 3 at the end), will start at 10:00 PM (the 2200), and run for 45 minutes. The 3 other fields are 0 because no station is running (second item), so there is no start time (5th item) and no run time for that station (6th item).
Next time I define String formats, I will certainly do it in a less ad hoc way!
Particle Variable TwitOnOff
This variable, will be one of 10, 20, 30 or 11, 21, 31. The second digit shows sprinkler status (0 = off/disabled, 1 = enabled). The first diit indicates if Tweets are disabled (3); program start and end only tweeting is enabled(1); program start, stations starts, and program end tweeting is enabled.
Particle Variables Debug_0, Debug_1, Debug_2, now, and pgmTotal
These variables are not used by the Android app. They were used in debugging firmware using Atomiot.