Start() - The Start Command
The Start() command actively listens to incoming messages and will start the task when a matching message is received. You can also manually start the task and it will just run past this command.
The basic version of this command triggers off of a specified preset and area. The advanced version triggers off of one or more DyNet packets.
Another advanced use is on some gateways to trigger off of custom packets similar to the StartX command. This use can automatically store the incoming data to memory locations.
The Start() command is very taxing on the processor of the device because it is required to check against every message on the network. That means that having too many of them can overwhelm the processor and cause the Start() commands to become unreliable. Try to avoid having more than 6 of them on a new device and more than 3 on a legacy device using an M16 processor. If you need more than 2 it is usually better to have one task that triggers off of all messages and then starts subtasks based on what the message was. |
Syntax
Start(A=a,P=p,J=j)
Where "a" is the area number, "p" is the preset number, and "j" is the join value.
Any message that matches all of these parameters will cause the task to start.
Area and Preset are required parameters but Join is optional. It will default to 0xFF if omitted.
There is no channel parameter for this command. If you want to trigger off a 0x6b message you must use the advanced version. |
Start(x,x,x,x,x,x,x)
Logical - Start(0x1C,Area,Data1,OpCode,Data2,Data3,Join)
Physical - Start(0x5C,DeviceCode,BoxNumber,OpCode,Data1,Data2,Data3)
This version listens to the network for defined values. An x is a wild card and can trigger off of any value. You can specify any portion of the packet, except for the checksum, and use wildcards for the rest.
This version of the command can trigger off of logical (0x1c), physical (0x5c), and DyNet2 (0xAC), packets.
Logical - Start(0xAC,OpCode,SourceDeviceCode,SourceBoxNumber,Area,Join,Data1,Data2,Data3)
Physical - Start(0xAC,OpCode,SourceDeviceCode,SourceBoxNumber,DestinationDeviceCode,DestinationBoxNumber,SubOpCode,Data1,Data2)
The structure for DyNet2 packets is more complicated than DyNet1 packets. A DyNet1 packet will simply check each byte against the 7 bytes in the Start() command. A DyNet2 Start() command will have 9 values and ignore most of the D2 packet but check key bytes against the values in the command.
Values like device code, area, or box number are 16bit values and will have two bytes in the Start() command.
Example: A start command triggering on area 65000 will have the 5th byte (Area) of 0xFDE8.
Although the Start() command discards most of the packet the entire message is still in the buffer so you will have to consider the full packet as individual bytes when using the copy command. |
Simple - Start("Hello")
ScanF Format - Start("%[*][width][length]specifier",x,y,z…)
Where the quotes contain the string and ScanF formatted modifiers. This is then followed by the memory locations you want to store that data to.
-
%d : Scan an integer as a signed decimal number.
-
%d : Scan an integer as a signed number. Similar to %d, but interprets the number as hexadecimal when preceded by 0x.+
-
%u : Scan for decimal unsigned int
-
%x : Scan an integer as an unsigned hexadecimal number.
-
%c : Scan a character (char). No null character is added.
-
%s : Scans a string. The scan terminates at whitespace. A null character is stored at the end of the string, which means that the buffer supplied must be at least one character longer than the specified input length.
-
%n : The number of characters read so far from stdin is stored in the pointed location. No input is consumed.
-
%% : A % followed by another % matches a single %.
-
* : An optional starting asterisk indicates that the data is to be read from the stream but ignored (i.e. it is not stored in the memory location pointed by an argument).
Width Specifies the maximum number of characters to be read in the current reading (optional) operation.
Length Alters the expected type of the storage pointed to by the corresponding (optional) argument. By default in this implementation the length of numbers is 1 byte.
To store a 2 byte number append length with lower case "L" (i.e. %ld). This allows for signed number greater than +/-127 and unsigned numbers greater than 255.
To store a 4 byte number append length two lowercase 'L’s (i.e. %lld).
Examples
Example 1
Basic Start() command.
Task14()
{
Name="Leaving Task"
Start(A=200,P=4) //Starts on P4 for Area 200
Preset=4
Fade=2
Delay=.2 //Set a default delay of 200ms
Preset(A=4) //Turn off the living room lights
Delay()
Preset(A=9) //Turn off the dining room lights
Delay()
Preset(A=5) //Turn off the kitchen lights
Delay()
Preset(A=11) //Turn off the bedroom lights
Null
}
Example 2
Advanced Start() command that is very targeted.
Task14()
{
Name="Do Not Disturb Tracker"
Start(0x1C,3,0x00,0x4C,0x00,x,0xFF) //Starts on DND for Area 3
Copy @5,$10,1 //Copies the DND state to $10
Null
}
Example 3
Advanced Start() command that is more broad.
Task1()
{
Name="Bogus Trigger task"
Start(0x1c,x,x,x,x,x,x) //Watches all incoming 1C logical messages.
copy @0,~0,7 //Copy the msg to ~0-~6. ~1 is area, ~3 is preset
LDA ~1 //Load the area
CMP #2 //Is it area 2?
BRZ Area2
CMP #3 //Is it area 3?
BRZ Area3
Null
Area2:
LDA ~3 //Get Preset byte (The Op code)
CMP #0x00 //Check if it the incoming Preset is Preset 1
BRZ A2P1 //If it matches branch down to P1: Label. If not continue.
CMP #0x03 //Check if it the incoming Preset is preset 4
BRZ A2P4
Null //Stop.
A2P1:
//Do something
Null
A2P4:
//Do something
Null
...
}
Example 4
Broad DyNet2 Start command.
Task1()
{
Name="DyNet2 Watcher Task"
Start(0xAC,x,x,x,x,x,0x00,x,x) //Trigger on a DyNet2 message
Copy @2,~50,8 //Copy 8 of the bytes starting at the 3rd byte and store into
//~50-59 ~50=Opcode 54&55=Area 58=preset base 1
LDA ~50 //Load the Accumulator with the opcode
CMP #0x01 //Is it a preset message?
BRZ D2_AREA_CHECK
Null
D2_AREA_CHECK:
LDA ~54 //Load the first Area Byte?
CMP #0xFD //Is it FD? (64768-65023)
BNE DYNET2_END //If not End
LDA ~55 //Load the second byte
CMP #0xE8 //Is the second byte E8? (65000)
BRZ GLOBAL_AREA1
CMP #0xE9 //Is the second byte E9? (65001)
BRZ GLOBAL_AREA2
CMP #0xEa //Is the second byte E8? (65002)
BRZ GLOBAL_AREA3
CMP #0xEb //Is the second byte E8? (65003)
BRZ GLOBAL_AREA4
CMP #0xEc //Is the second byte E8? (65004)
BRZ GLOBAL_AREA5
Null
GLOBAL_AREA1:
LDA ~58 //Get the preset byte. D2 presets are linear with a base of 1.
CMP #1 //Is it Preset 1? (Day)
BRZ DAY_NIGHT_P1
CMP #2 //Is it Preset 2? (Dawn)
BRZ DAY_NIGHT_P2
CMP #3 //Is it Preset 3? (Dusk)
BRZ DAY_NIGHT_P3
CMP #4 //Is it Preset 4? (Night)
BRZ DAY_NIGHT_P4
Null
DAY_NIGHT_P1:
...
}
Example 5
Targeted DyNet2 start command.
Task14()
{
Name="Area 65000"
Start(0xAC,0x01,x,x,0xFDE8,0xFF,0x00,x,x) //Trigger on a D2 A65000 Preset message
Copy @10,~0,1 //Copy preset messages for area 65000 store bytes 10-11
LDA ~0 //Load the Accumulator with the Value in ~0
CMP #1 //If Equal to 1
BRZ Preset1 //Branch to Label "Preset1"
CMP #2 //If Equal to 2
BRZ Preset2 //Branch to Label "Preset2
Null
...
}
Example 6
Advanced Start() command on a simple string.
Task14()
{
Name="Welcome Task"
Start("Hello") //Starts on the string "Hello"
...
}
Example 7
Advanced Start() command on a string using specifiers.
Task14()
{
Name="Temperature capture"
Start("Temp A%d %d.%d",~7,~6,~5) //The command matches any incoming packet that starts with "Temp", a space, the letter "A" and a number, a space, and a number with a decimal point, and another number. The numbers are stored in ~7, ~6 and ~5 respectively. ex "Temp A5 24.5"
...
}
Example 8
Advanced Start() command on a string using specifiers to ignore some values.
Task14()
{
Name="Partial capture task"
Start("B. %*4s F%d %d.%d",~4,~5,~6) //The command matches any incoming packet that starts with the letter "B" and a full stop, a space, a four character string that is ignored, a space, the letter "F" and a number, a space and a number with a decimal point and another number. The numbers are stored in ~4, ~5 and ~6 respectively.
...
}
Example 9
Advanced Start() command on a string using specifiers.
Task14()
{
Name="Volume capture"
Start("Volume%d %ld",~20,~21) //Starts on any incoming packet that starts with "Volume" and then a number, a space and then another number. The first number will be stored in ~20 and the second number in ~21 and ~22. for example: Volume5 337
...
}
Example 10
Catches ASCII commands from iLight system and stores the values for Dynalite. It ignores carriage returns. @SS5:A10:F2 and @SS550:A1000:F266 are both captured but this one task.
Task14()
{
Name="iLight capture"
Start("@SS%ld:A%ld:F%ld",~40,~42,~44) //Starts on any incoming iLight packet Scene Number is stored into 40&41, Area number is stored into 42&43, Fade time is stored into 44&45.
//The task would need to check the high bytes and decide if the Dynalite message needs to be D2 or not.
//It would also need to use linear presets or convert preset numbers to opcodes/preset banks.
//Notice that the carriage return is ignored as it is trailing data that is not important.
...
}