Skip to content

Configuration

Jump to bottom
Atis Elsts edited this page Jan 21, 2022 · 6 revisions

A configuration file fully describes a simulation scenario. Configuration files are passes as parameters to the simulation application, either using the command line or the web interface. A single run of the simulation application normally corresponds to the execution of simulation defined in a single configuration file.

It is not necessary to fill in all configuration values in a configuration file. The missing values simply take their default settings.

Main configuration

Simulation parameters

  • SIMULATION_DURATION_SEC - The total duration of the simulation, seconds. Positive integer or floating point number, default: 600.

  • SIMULATION_SEED - Random seed. Integer, default: 0.

  • SIMULATION_NUM_RUNS - Number of runs. Each subsequent run gets random seed incremented by one. Positive integer, default: 1.

  • SIMULATION_SCRIPT_FILE - JavaScript file with user-defined code to be executed when the simulation is loaded and when specific ASN numbers are reached. Filename, default: null.

  • SIMULATION_WITH_PACKET_COLLISIONS - Simulate packet collisions? If disabled, all colliding packets can be received. Boolean, default: true.

  • EMULATE_COOJA - Try to emulate the specific behavior of Cooja with the aim to achieve maximum reproducibility. Boolean, default: false.

  • EMULATE_6TISCHSIM - Try to emulate the specific behavior of the 6tisch simulator of the OpenWSN. Boolean, default: false.

  • EMULATE_CONTIKI - Try to emulate the specific behavior of the Contiki/Contiki-NG RPL and TSCH implementations. Boolean, default: false.

Scheduling parameters

  • SCHEDULING_ALGORITHM - The name of the scheduler to use. String, default: "Orchestra". Available: "Orchestra", "6tischMin", "LeafAndForwarder".

Other scheduling parameters are defined by the respective schedulers. Follow their documentation to learn more about them.

Network stack parameters

  • MAC_HOPPING_SEQUENCE - The default hopping sequence of the TSCH network. Either a string (name or a predefined hopping sequence) or an array of channels, e.g. [15, 25, 20, 26]. Default: "TSCH_HOPPING_SEQUENCE_4_4".
  • MAC_JOIN_HOPPING_SEQUENCE - The hopping sequence used for joining (the channel scan process). If null, the default hopping sequence is used instead. Same format as for MAC_HOPPING_SEQUENCE. Default: null.
  • MAC_START_JOINED - Start with all nodes in a joined state? Boolean, default: false.
  • MAC_MAX_RETRIES - The maximum number of packet re-transmissions. Non-negative integer, default: 7.
  • MAC_QUEUE_SIZE - The maximum number of outgoing packets towards each neighbor. Positive integer, default: 16.
  • MAC_MAX_SUBSLOTS - The maximum number of active subslots in a single TSCH slot (1 in standard TSCH). Non-negative integer, default: 1.
  • MAC_SLOT_DURATION_US - TSCH slot duration in microseconds. Positive integer, default: 10000.
  • MAC_MAX_JOIN_PRIORITY - The maximum acceptable TSCH join priority. Nodes will not accept a time-source node that sends EB with join priority greater than this number. Positive integer, default: 32.
  • MAC_CHANNEL_SCAN_DURATION_SEC - How long to scan each channel in the scanning phase. Positive number, default: 1.
  • MAC_MIN_BE - The minimum value of the CSMA backoff exponent. Non-negative integer, default: 1.
  • MAC_MAX_BE - The minimum value of the CSMA backoff exponent. Non-negative integer that is equal or greater than MAC_MIN_BE. Default: 5.
  • MAC_KEEPALIVE_TIMEOUT_SEC- The maximum time before sending a unicast keep-alive message to the time source. Set to 0 to disable. Nonnegative number, default: 60.
  • MAC_DESYNC_THRESHOLD_SEC - The maximum time without synchronization before leaving the PAN. Normally, should be larger than twice the value of MAC_KEEPALIVE_TIMEOUT_SEC. Set to 0 to disable. Nonnegative number, default: 120.
  • MAC_EB_PERIOD_SEC - Initial period between two consecutive EBs. Positive number, default: 16.
  • MAC_MAX_EB_PERIOD_SEC - The maximum period between two consecutive EBs. Positive number, default: 16.
  • MAC_EB_PACKET_SIZE - The size of EB packets in bytes, including MAC header. Positive number, default: 35.
  • MAC_MAX_PACKET_SIZE - Max MAC packet size, excluding header. 105=127-2-20 is typical: 127 is the limit for IEEE 802.15.4 radios, 2 used by the frame check sequence (FCS), 20 bytes by MAC header. Positive integer, default: 105.
  • MAC_HEADER_SIZE - The assumed MAC header size. 20 bytes is a sensible dummy value; to get a standard-compliant operation would need to implement the whole IEEE 802.15.4 packet framing logic. Not relevant for EB packets - header overhead is already a part of the MAC_EB_PACKET_SIZE parameter. Positive integer, default: 20.
  • ROUTING_MAX_ROUTES - The maximum number of routes. A value of zero or less than zero is treated as a unlimited. If EMULATE_CONTIKI is set, 16 is used as the default. Otherwise, not limited by default.
  • ROUTING_ALGORITHM - Routing algorithm. Available options: "RPL", "LeafAndForwarderRouting", "NullRouting". Default: "RPL".
  • ROUTING_IS_LEAF - Is this node a leaf in the routing tree, i.e. one that does not forward packets? Booelean, default: false.
  • NET_MAX_NEIGHBORS - The maximum number of neighbors. Relevant to all layers of the network (MAC, IP, and routing). A value of zero or less than zero is treated as a unlimited. If EMULATE_CONTIKI is set, 8 is used as the default. Otherwise, not limited by default.
  • IP_FRAGMENTATION_ENABLED - Enable fragmentation? If not enabled, packets larger than max MAC packet size are simply dropped. Boolean, default: true.
  • IP_REASSEMBLY_TIMEOUT_SEC - IP packet reassembly maximal time. Seconds, default: 8.0.***
  • PHY_CO_CHANNEL_REJECTION_DB - Co-channel rejection threshold. This is required to implement the radio capture effect in the simulator. The co-channel rejection threshold depends on the chip and technology; some typical values are: 802.15.4 radios: -3 dB, BLE radios: -8 dB, FLRC radios: -10 dB. A number, default: -3.

Application parameters

  • APP_PACKET_SIZE - Size of application packets, excluding IP and MAC headers. Positive number, default: 100.
  • APP_PACKET_PERIOD_SEC - Data packets are generated once per this period. If set to 0, packet generation is disabled. Nonnegative number, default: 60.
  • APP_WARMUP_PERIOD_SEC - Data packets are not generated before this warm-up period has ended after the start of the simulation. Non-negative number, default: 100.
  • APP_COOLDOWN_PERIOD_SEC - Data packets are not generated after this cool-down period has started before the end of the simulation. Non-negative number, default: 0.
  • APP_PACKETS_GENERATE_ALWAYS - If set to true, data packets are generated even if the node is not connected to a network. Boolean, default: false.

Network autogeneration

  • POSITIONING_NUM_NODES - The number of node to automatically create. Used when nodes are not explicitly defined in NODE_TYPE config. Positive integer, default: 7.
  • POSITIONING_LAYOUT - Type of positioning. Available options: "Star", "Line", "Grid", "Mesh". Default: "Star".
  • POSITIONING_LINK_QUALITY - For line and grid networks, this determines the neighbor distance, for star networks: the radius. For mesh networks, this is used as threshold: a link is "good" if its success rate is above this number. A number between 0.0 and 1.0, default: 0.9.
  • POSITIONING_NUM_DEGREES - For mesh networks: the average number of good links from a node. Between 2 and NUM_NODES-1. If not set, selected as sqrt(NUM_NODES). Default: null (not set).
  • POSITIONING_RANDOM_SEED - The positioning module may get its own random seed to enable repeatable network generation. Integer or null, default: null (not set).

Mobility parameters

  • MOBILITY_MODEL - The name of the mobility model. Available options: "Static", "Line", "RandomWaypoint". Default: "Static".
  • MOBILITY_UPDATE_PERIOD_SEC - How often to update mobile node positions? Simulation performance is affected by this setting: the shorter the period, the better the accuracy, but the slower the simulation. Positive number, default: 10.
  • MOBILITY_RANGE_X - The nodes move in two dimensions, x \in [0, MOBILITY_RANGE_X], y \in [0, MOBILITY_RANGE_Y]. Non-negative number, default: 300.
  • MOBILITY_RANGE_Y - Non-negative number, default: 300.
  • MOBILITY_SPEED - Speed of mobile nodes in meters per second. A number, default: 0.1

Web interface configuration

  • WEB_ENABLED - whether access from the web interface is enabled. If so, a web server is created instead of running a simulation normally. Boolean, default: false.
  • WEB_PORT - the port number to use for web connections. Integer, default: 2020.
  • WEB_MAX_LOGS - the number of most recent log entries to serve to the web interface on a request. Non-negative integer, default: 1000.
  • WEB_MAX_CELLS - the number of most recent cell statuses to serve to the web interface on a request. Non-negative integer, default: 1000.

Logging and output statistics

  • LOG_FILE - the name of a log file. If a relative path, assumed to be relative to the configuration file. If null, filename log.txt in the results directory is used. Default: null.
  • LOG_LEVELS - user-defined log levels for various topics. A dictionary of type string -> integer ("topic" -> log_level). Not set by default.
  • LOG_LEVELS_DEFAULT - the default logging levels for various predefined topics. A dictionary of type string -> integer ("topic" -> log_level). Should not be redefined by the user: use LOG_LEVELS instead! Default values are 3 for all topics.
  • LOG_LEVEL_DEFAULT_NOTOPIC - the log level for topics not included in the LOG_LEVELS_DEFAULT and LOG_LEVELS dictionaries. Non-negative integer, default value: 3.
  • SAVE_RESULTS - whether to save simulation results in files. Boolean, default value: true.
  • RESULTS_DIR - if SAVE_RESULTS is set to true, then simulation result files are stored in this directory. The directory is created if it does not exist. If null, it is set automatically to the directory tsch-sim/results/<currentdatetime>. Default value: null.

Node type configuration

A node type is a template for a specific subset of nodes. It allows to define the number and IDs of the nodes, as well as override the global and default configuration values with node type specific settings. Finally, it also allows to define connections between the nodes, using which network packets can be exchanged.

  • NAME - The name of this node type. Mandatory (no default value).
  • COUNT - The number of nodes of this type. Positive integer. Mandatory (no default value).
  • START_ID- The first ID of nodes of this type. Overlapping ID ranges are not allowed. A node with ID 1 (the TSCH coordinator) must be present in a simulation. Default value set automatically to the last ID of the previous node type incremented by 1, or to 1 if this is the first node type. Positive integer in range [1..65535].
  • CONNECTIONS - the outgoing connections from nodes of this type; see below for the format. No default value.
  • POSITIONS - the positions of nodes of this type; see below for the format. Default value: both X and Y coordinates equal to 0 for all nodes.
  • APP_PACKETS - application data packets to generate from the node of this type; see below for the format. No default value.

Node connections

These settings are configured using the CONNECTIONS array, either inside a NODE_TYPE or in the global configuration object.

The following fields can be present for each entry:

  • TO_NODE_TYPE - The connection is made to all nodes of this type.
  • FROM_NODE_TYPE - The connection is made from all nodes of this type. Ignored if specified inside a NODE_TYPE definition.
  • NODE_TYPE - Connection are made between all nodes of this type, in both directions. Ignored if specified inside a NODE_TYPE definition.
  • TO_ID - The ID of a specific destination node. Overrides TO_NODE_TYPE.
  • FROM_ID - The ID of a specific source node. Overrides FROM_NODE_TYPE.
  • LINK_MODEL - The name of the link model to use. String. Default value LogisticLoss unless EMULATE_6TISCHSIM is enabled in the configuration. In the latter case, the default value is PisterHack.
  • RSSI - Received Signal Strength Indicator. Valid only for some link models, such as the Fixed link model. Default value depends on the link model. Default: -70.
  • LINK_QUALITY - link quality. Number between 0.0 and 1.0, inclusive. Valid only for some link models, such as the Fixed link model. Default value depends on the link model. Default: 1.0.

Node positioning

Automated positioning

Network autogeneration (see above) implies that positioning is also done automatically, based on the POSITIONING_ configuration.

For networks that are not automatically generated, POSITIONING_ configuration is still used to distribute the nodes across the network, unless positions are manually configured for any nodes (see below). If POSITIONING_ configuration is disabled, the default node position (0.0, 0.0) is used for all nodes.

Manually configured node positions

Node positions can be configured manually, using the POSITIONS array, either inside a NODE_TYPE or in the global configuration object. If the position is configured for any nodes, no nodes in the network are automatically positioned.

The following fields can be present for each entry:

  • ID - the ID of the node. Must be a valid node ID; mandatory (no default value).
  • X - the X starting coordinate of the node. Number, default value 0.0.
  • Y - the Y starting coordinate of the node. Number, default value 0.0.

Application data

These settings are configured using the APP_PACKETS object, either inside a NODE_TYPE or in the global configuration object.

The following fields can be present:

  • TO_ID - The ID of a specific destination node, or -1 for broadcast. Broadcasts can be received by all directly connected nodes. Must be a valid node ID or -1; default value -1.
  • TO_TYPE - The type of the destination nodes. Ignored if TO_ID is also set. If specified, must be a valid node type; no default value.
  • FROM_ID - The ID of a specific source node. Ignored if specified inside a NODE_TYPE. If specified, must be a valid node ID; no default value.
  • APP_PACKET_PERIOD_SEC - Packet generation period. Positive integer, default value - the global configuration value of APP_PACKET_PERIOD_SEC.
  • APP_PACKET_SIZE - Packet size, including IP and MAC headers. Positive integer, default value - the global configuration value of APP_PACKET_PERIOD_SEC.
  • IS_QUERY - If set, a reply packet addressed to the source node is generated on the destination node upon reception of the packet. Boolean, default: false.

Module configuration

Some TSCH-Sim modules define their own configuration. These modules include:

See the documentation of the respective modules for details.

Clone this wiki locally