Main Content

scheduleAction

Schedule action to perform during simulation

Since R2022b

collapse all in page

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

    Syntax

    scheduleAction(networkSimulator,callbackFcn,userData,startTime)
    scheduleAction(___,periodicity)
    actionID = scheduleAction(___)

    Description

    scheduleAction(networkSimulator,callbackFcn,userData,startTime) schedules an action to perform during the wireless network simulation. The callbackFcn argument specifies the action to be performed at the specified time, startTime, and userData specifies the input data to use for the specified action.

    example

    scheduleAction(___,periodicity) specifies to repeat the action at regular or irregular time intervals, in addition to all input arguments from the previous syntax.

    actionID = scheduleAction(___) returns an identifier specifying the action scheduled.

    Examples

    collapse all

    This example uses:

    Open Live Script

    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 displayInfo to define the actions for the simulator to perform during simulation. You can define an one time action, periodic action, and action when simulator advances in time. The input data for the custom function is stored as a structure and passed using the scheduleAction function.

    A) Schedule One Time Action

    For the one time action, the displayInfo function displays the details of the nodes in the network.

    Specify the ActionType input argument value of displayInfo function as "OneTime". Specify the names of the nodes in the network as input to displayInfo function.

    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;
scheduleAction(networkSimulator,@displayInfo,userdata,startTime);

    B) Schedule Periodic Action

    For the periodic action, the displayInfo function displays the physical layer statistics of the central node in the Bluetooth BR network.

    Specify the ActionType input argument value of displayInfo function as "Periodic". Specify the central node and the simulator as inputs to displayInfo function.

    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.002s starting from the beginning of the simulation.

    startTime = 0;
periodicity = 0.002;
scheduleAction( ...
    networkSimulator,@displayInfo,userdata,startTime,periodicity);

    C) Schedule Action When Simulator Advances in Time

    When the simulator advances in time, the displayInfo function displays the next event time of the simulator.

    Specify the ActionType input argument value of displayInfo function as "TimeAdvance". Specify the simulator as input to the displayInfo function.

    userdata = struct( ...
    ActionType="TimeAdvance", ...
    Simulator=networkSimulator);

    Set the periodicity value to 0. Configure the simulator by using the scheduleAction function to display the time of the next event.

    startTime = 0;
periodicity = 0;
scheduleAction( ...
    networkSimulator,@displayInfo,userdata,startTime,periodicity);

    Run Simulation

    Specify the simulation time in seconds.

    simulationTime = 0.003;

    Run the simulation for the specified simulation time.

    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-------
-------Action When Simulator Advances in Time-------
Simulator next event time is at 0.00037 seconds
-------End-------
-------Action When Simulator Advances in Time-------
Simulator next event time is at 0.00063 seconds
-------End-------
-------Action When Simulator Advances in Time-------
Simulator next event time is at 0.00075 seconds
-------End-------
-------Action When Simulator Advances in Time-------
Simulator next event time is at 0.00100 seconds
-------End-------
-------One Time Action -------
Node details:
Name: Node1 ID: 1 Role: central
Name: Node2 ID: 2 Role: peripheral
-------End-------
-------Action When Simulator Advances in Time-------
Simulator next event time is at 0.00108 seconds
-------End-------
-------Action When Simulator Advances in Time-------
Simulator next event time is at 0.00125 seconds
-------End-------
-------Action When Simulator Advances in Time-------
Simulator next event time is at 0.00162 seconds
-------End-------
-------Action When Simulator Advances in Time-------
Simulator next event time is at 0.00187 seconds
-------End-------
-------Action When Simulator Advances in Time-------
Simulator next event time is at 0.00200 seconds
-------End-------
-------Periodic Action -------
Statistics of Node1 at time 0.002 seconds:
                   ReceivedPackets: 2
                    DecodeFailures: 0
                  PacketCollisions: 0
               CoChannelCollisions: 0
               CollisionsWithBREDR: 0
            CollisionsWithNonBREDR: 0
    CollisionsWithBREDRAndNonBREDR: 0
                TransmittedPackets: 2
                   TransmittedBits: 732

-------End-------
-------Action When Simulator Advances in Time-------
Simulator next event time is at 0.00200 seconds
-------End-------
-------Action When Simulator Advances in Time-------
Simulator next event time is at 0.00216 seconds
-------End-------
-------Action When Simulator Advances in Time-------
Simulator next event time is at 0.00250 seconds
-------End-------
-------Action When Simulator Advances in Time-------
Simulator next event time is at 0.00287 seconds
-------End-------

    function displayInfo(~,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")
    case "TimeAdvance"
        fprintf("-------Action When Simulator Advances in Time-------\n")
        fprintf("Simulator next event time is at %.5f seconds\n", ...
            userdata.Simulator.CurrentTime)
        fprintf("-------End-------\n")
end
end

    Input Arguments

    collapse all

    Wireless network simulator, specified as a wirelessNetworkSimulator object.

    Callback function to run at the specified time, specified as a function handle. The callback function is a custom function defining an action to be performed during the wireless network simulation. The syntax for the callback function must be:

    callbackFcn(actionID,userData)

    Input to the callback function, specified as a numeric value, character vector, or string scalar. If the callback function does not require any input, specify the userData value as [ ]. To pass multiple values as input to the callback function, specify the input as a structure or a cell array.

    Absolute simulation time at which a scheduled action is to be performed, specified as a nonnegative scalar. Units are in seconds.

    • If you specify the simulation time as zero, the simulator performs the scheduled action at the start of simulation.

    • If you specify both startTime and periodicity, the simulator performs the scheduled action at the specified simulation time and repeats the action until the end of simulation. The time interval for repeating the action is specified by the periodic time in periodicity.

    Periodic time, specified as a nonnegative scalar. The periodic time is the time interval at which the scheduled action repeats. Units are in seconds.

    • For periodic actions, the periodicity value must be greater than zero.

    • If the periodic time value is 0, the scheduled action is performed whenever the simulator advances in time in response to an event. The events can occur at regular or irregular time intervals. In this case, the simulator ignores the value of startTime.

    Output Arguments

    collapse all

    Unique identifier for action, returned as an integer. You can also use this value to cancel a scheduled action by using the cancelAction function.

    Version History

    Introduced in R2022b

    expand all

    See Also

    Objects

    Functions

    Topics