cancelAction

Cancel scheduled action

Since R2022b

Download Required: To use cancelAction, first download the Communications Toolbox Wireless Network Simulation Library add-on.

Syntax

cancelAction(networkSimulator,actionID)

Description

cancelAction(networkSimulator,actionID) cancels an action scheduled to be performed during the specified wireless network simulation.

Examples

Schedule and Cancel Actions During Network Simulation

Simulate Bluetooth BR Network

Create a wirelessNetworkSimulator object by using the wirelessNetworkSimulator.init() function. By default, the wirelessNetworkSimulator object applies free-space path loss model for the channel effects.

networkSimulator = wirelessNetworkSimulator.init();

Create two Bluetooth BR nodes, one with the "central" role and other with the "peripheral" role. Specify the position of the Peripheral node in meters.

centralNode = bluetoothNode("central");
peripheralNode = bluetoothNode("peripheral",Position=[1 0 0]);

Create a default Bluetooth BR connection configuration object to configure and share a connection between Bluetooth BR Central and Peripheral nodes.

cfgConnection = bluetoothConnectionConfig;

Configure connection between the Central and the Peripheral nodes.

connection = configureConnection( ...
    cfgConnection,centralNode,peripheralNode);

Create and configure a networkTrafficOnOff object to generate an On-Off application traffic pattern.

traffic = networkTrafficOnOff(DataRate=200,PacketSize=27, ...
    GeneratePacket=true,OnTime=inf);

Add application traffic from the Central to the Peripheral node.

addTrafficSource(centralNode,traffic,DestinationNode=peripheralNode);

Add the Central and Peripheral nodes to the wireless network simulator.

addNodes(networkSimulator,[centralNode peripheralNode]);

Schedule Action

Create a custom function statusInfo to define an one time action and periodic action for the simulator to perform during simulation. The input data for the custom function is stored as a structure and passed using the scheduleAction function. For the one time action, the statusInfo function displays the node details when the simulation time is 0.001s. For the periodic action, the statusInfo function displays the physical layer statistics of the central node in the Bluetooth BR network.

Specify the ActionType input argument of statusInfo function as "OneTime". Also, specify the names of the nodes in the network as input.

userdata = struct( ...
    ActionType="OneTime", ...
    Nodes=[centralNode peripheralNode]);

Configure the simulator by using the scheduleAction function to display the node details when the simulation time is 0.001s.

startTime = 0.001;
actionID1 = scheduleAction( ...
    networkSimulator,@statusInfo,userdata,startTime);

Specify the ActionType input argument value of statusInfo function as "Periodic". Also, specify the central node and the simulator as inputs.

userdata = struct( ...
    ActionType="Periodic", ...
    CentralNode=centralNode, ...
    Simulator=networkSimulator);

Configure the simulator by using the scheduleAction function to display the physical layer statistics of the central node at a time interval of 0.02s starting from the beginning of the simulation.

startTime = 0;
periodicity = 0.02;
actionID2 = scheduleAction( ...
    networkSimulator,@statusInfo,userdata,startTime,periodicity);

Cancel Action

To cancel a scheduled action, use the cancelAction function. Specify the value of the unique identifier denoting the action. The identifier is returned by the scheduleAction function.

cancelAction(networkSimulator,actionID1)

Run Simulation

Specify the simulation time in seconds.

simulationTime = 0.1;

Run the simulation for the specified simulation time. You can notice that the one time action scheduled to perform at 0.001s is cancelled. The simulator performs only the scheduled periodic action.

run(networkSimulator,simulationTime);

-------Periodic Action -------
Statistics of Node1 at time 0.000 seconds:
                   ReceivedPackets: 0
                    DecodeFailures: 0
                  PacketCollisions: 0
               CoChannelCollisions: 0
               CollisionsWithBREDR: 0
            CollisionsWithNonBREDR: 0
    CollisionsWithBREDRAndNonBREDR: 0
                TransmittedPackets: 1
                   TransmittedBits: 366

-------End-------
-------Periodic Action -------
Statistics of Node1 at time 0.020 seconds:
                   ReceivedPackets: 16
                    DecodeFailures: 0
                  PacketCollisions: 0
               CoChannelCollisions: 0
               CollisionsWithBREDR: 0
            CollisionsWithNonBREDR: 0
    CollisionsWithBREDRAndNonBREDR: 0
                TransmittedPackets: 17
                   TransmittedBits: 6222

-------End-------
-------Periodic Action -------
Statistics of Node1 at time 0.040 seconds:
                   ReceivedPackets: 32
                    DecodeFailures: 0
                  PacketCollisions: 0
               CoChannelCollisions: 0
               CollisionsWithBREDR: 0
            CollisionsWithNonBREDR: 0
    CollisionsWithBREDRAndNonBREDR: 0
                TransmittedPackets: 33
                   TransmittedBits: 12078

-------End-------
-------Periodic Action -------
Statistics of Node1 at time 0.060 seconds:
                   ReceivedPackets: 48
                    DecodeFailures: 0
                  PacketCollisions: 0
               CoChannelCollisions: 0
               CollisionsWithBREDR: 0
            CollisionsWithNonBREDR: 0
    CollisionsWithBREDRAndNonBREDR: 0
                TransmittedPackets: 49
                   TransmittedBits: 17934

-------End-------
-------Periodic Action -------
Statistics of Node1 at time 0.080 seconds:
                   ReceivedPackets: 64
                    DecodeFailures: 0
                  PacketCollisions: 0
               CoChannelCollisions: 0
               CollisionsWithBREDR: 0
            CollisionsWithNonBREDR: 0
    CollisionsWithBREDRAndNonBREDR: 0
                TransmittedPackets: 65
                   TransmittedBits: 23790

-------End-------
-------Periodic Action -------
Statistics of Node1 at time 0.100 seconds:
                   ReceivedPackets: 80
                    DecodeFailures: 0
                  PacketCollisions: 0
               CoChannelCollisions: 0
               CollisionsWithBREDR: 0
            CollisionsWithNonBREDR: 0
    CollisionsWithBREDRAndNonBREDR: 0
                TransmittedPackets: 81
                   TransmittedBits: 29646

-------End-------

function statusInfo(~,userdata)
switch(userdata.ActionType)
    case "Periodic"
        fprintf("-------Periodic Action -------\n")
        fprintf("Statistics of %s at time %.3f seconds:\n", ...
            userdata.CentralNode.Name, ...
            userdata.Simulator.CurrentTime);
        stats = statistics(userdata.CentralNode);
        disp(stats.PHY)
        fprintf("-------End-------\n")
    case "OneTime"
        fprintf("-------One Time Action -------\n")
        fprintf("Node details:\n")
        for idx=1:numel(userdata.Nodes)
            fprintf("Name: %s ID: %d Role: %s\n", ...
                userdata.Nodes(idx).Name, ...
                userdata.Nodes(idx).ID, ...
                userdata.Nodes(idx).Role)
        end
        fprintf("-------End-------\n")
end
end

Input Arguments

networkSimulator — Wireless network simulator

wirelessNetworkSimulator object

Wireless network simulator, specified as a wirelessNetworkSimulator object.

actionID — Unique identifier of action to cancel

positive scalar integer

Unique identifier of action to cancel, specified as a positive scalar integer. The unique identifier is returned by the scheduleAction function.

Version History

Introduced in R2022b

R2023a: Moved to Communications Toolbox Wireless Network Simulation Library from Bluetooth Toolbox

Previously, this wirelessNetworkSimulator object function required Bluetooth^® Toolbox.