Stop() - The Stop Command

The Stop() command actively listens to incoming messages and will stop the task when a matching message is received. When started the task 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.
Unlike the Start() this command will trigger on a task that is currently running.

A task can have multiple Stop() commands but typically would only have one.
A task can have both a Stop() commands and Start() commands.

If the Stop() command and Start() commands trigger off of the same messages the task will run for a few milliseconds before stopping regardless of the order.
The Stop() 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 Stop() 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.
Like the Start() command it doesn’t matter where in the task this command lives. It could even be at the end after a null and it will still function.

Syntax

Basic Version

Stop(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 stop.
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 stop the task with a 0x6b message you must use the advanced version.
Advanced Version - DyNet1

Stop(x,x,x,x,x,x,x)
Logical - Stop(0x1C,Area,Data1,OpCode,Data2,Data3,Join)
Physical - Stop(0x5C,DeviceCode,BoxNumber,OpCode,Data1,Data2,Data3)
Block Data - Stop(0x6C,Data1,Data2,Data3,Data4,Data5,Data6)
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), block data (0x6c), and DyNet2 (0xAC) packets. On most devices this check occurs after the D2 to D1 translator and the DyNet 1 version will trigger off DyNet 2 packets that match.

Advanced Version - DyNet2

Logical - Stop(0xAC,OpCode,SourceDeviceCode,SourceBoxNumber,Area,Join,Data1,Data2,Data3)
Physical - Stop(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 Stop() command. A DyNet2 Stop() 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 Stop() command.

Example: A stop command triggering on area 65000 will have the 5th byte (Area) of 0xFDE8.

The DyNet1 version of this command uses Join as a filter so if any bytes in the message match the join value in the Stop() command the task will trigger. The DyNet2 version of this command uses join as a Gate so only messages with an exact match to the join value will stop the task.
Advanced Version - Custom Packets

Simple - Stop("Stop")
ScanF Format - Stop("%[*][width][length]specifier",x,y,z…​) Where the quotes contain the string and ScanF formatted modifiers. This is then followed by the tilde memory locations you want to store that data to. You cannot use this to save directly to persistent memory locations.

Supported Specifiers
  • %d : Scan an integer as a signed decimal number.

  • %i : 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 integer.

  • %x : Scan an integer as an unsigned hexadecimal number.

  • %c : Scan a character (char). No null character is added.

  • %Xs : Scans a string. "X" is the number of characters to capture. 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 tilde 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() and Stop() commands.

Task14()
{
Name="Leaving Task"
Start(A=200,P=4) //Starts on P4 for Area 200
Stop(A=200,P=1)  //End if the welcome trigger is heard
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

Start and stop commands to control an RGB Chase.

Task1()

{
Start(A=100,P=1)    //Start on and Area 100 P1 message
Stop(A=100,P=4)     //Stop on an Area 100 P4 message
Area=11             //Set Default Area to 11 (RGB Lights)
Delay=1.5           //Set Default Delay time to 1.5s
Fade=1              //Set Default Fade time to 1s
Loop:
    Preset(P=5)     //Recall Preset 5 (Red)
    Delay()         //Delay between colors
    Preset(P=6)     //Recall Preset 6 (Yellow)
    Delay()
    Preset(P=7)     //Recall Preset 7 (Green)
    Delay()
    Preset(P=8)     //Recall Preset 8 (Teal)
    Delay()
    Preset(P=9)     //Recall Preset 9 (Blue)
    Delay()
    Preset(P=10)    //Recall Preset 10 (Magenta)
    Delay()
    BRA Loop        //Loop back to the top and repeat.
}

Example 3

Advanced Stop() command that is very targeted.

Task14()
{
Name="Do Not Disturb Tracker"
Stop(0x1C,3,0x00,0x4C,0x00,x,0xFF)      //Stops on DND for Area 3
...
}

Example 4

Advanced Stop() command that is more broad.

Task1()
{
    Name="Bogus Trigger task"
    Start(0x1c,x,x,x,x,x,x) //Watches all incoming 1C logical messages. Starts on any logical message.
    Stop(0x1c,250,x,x,x,x,x) //Watches all incoming 1C logical messages. Stops the task if the area is 250.
    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 5

Targeted DyNet2 stop command.

Task14()
{
Name="Area 65000"
Stop(0xAC,0x01,x,x,0xFDE8,0xFF,0x00,x,x) //Stop the task on a D2 A65000 Preset message with join of 0xFF
...
}

Example 6

Advanced Stop() command on a simple string.

Task14()
{
Name="Welcome Task"
Start("Hello")      //Starts on the string "Hello"
Stop("GoodBye")     //Stops on the string "GoodBye"
...
}

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"
Stop("HVAC A%d Mode%d",~8,~9)     //The task will stop on any string that starts with "HVAC", a space, the letter "A" and a number, a space, "Mode" and a number. The numbers are stored in ~8, and ~9 respectively. ex "HVAC A1 Mode3"
...
}