MeshProtocolSimulator v1.0.0

MeshProtocolSimulator is console application programmed in C++ which can emulate virtual wireless environment for MeshNet protocol. The simulation can detect interference between nodes and interfered frame won't be received by nodes. Environmental noise or link quality cannot be simulated right now, but we want to implement it. The simulation can be controlled by commands or by scenario file. Simulation process can be recorded to log file, which can be later analyzed.

Main classes

Emulator class controlls whole simulation. This class allows interventions in the simulation or can invoke functions like: send, receive, connect, disconnect, ping, network scan, etc. Network topology is also specified in this class thanks to array of NodeConnections structures, which defines link between two nodes. Network topology can be default or can be specified in scenario file. Default topology looks like this:

where numbers are MeshMAC addresses and node 1 is gateway. This class also controlls timing of the simulation for each node. Although each NodeSimulator instance has its own thread, only the code of one node can be processed at a time. This is because code for all nodes in virtual network has to be done simultaneously for proper timing, but CPUs has only limited count of cores, which can also process threads of another applications. We solved this by executing the code of only one node that is far behind in the simulation. Code execution is paused when a node sends or receives a frame or tries to determine the number of received frames by calling available() function or one cycle from infinity loop on a node was done.
NodeSimulator class handles simulation of one Node. It also describes the node behavior with structure NodeSettings. This class also handles frames sending and receiving. Those frames are sent as RawMessage. It also checks if interference happened. There are two types of interferences which may occur:
- hidden terminal interference which may happen when two nodes (let's say A and C) simultaneously transmits data and node B hears transmission from A and C. Both messages will be discarded on node B, because in reality, they will be interfered. But when there is node D, which can hear only node A, it will receive this message, because it is not interfered.
- half-duplex collision which may happen when node A transmits data, but also node B transmits data. Wireless communication on one channel is always half-duplex, so these nodes will not receive data from each other because they are busy transmitting.
RawMessage structure represents raw message, that was sent between two virtual radios. It has no header and data are not structured.
Simulation_RFI class is interface, which behaves as real radio, which is described by NodeSettings.

Simulation control and settings

Simulation contol can be dividen into 4 phases:

Launching simulation happens when console application is launched. Simulation can be setup by arguments and switches:
- -a or --autopause - If set, auto pause is enabled. Simulation will be auto paused after one second of inactivity. Simulation is also paused at the beginning of simulation.
- -o or --logonly - Can be used only if log file path is specified. Simulation logs are not showed to screen but are written only to specified log file.
- -r or --raw - Output showed on screen will be in raw form. This is recommended to use, when output is redirected to some application, which controls simulation.
- -s - After this switch scenario file path must be specified.
- -l - After this switch log file path must be specified.
- -h or --help shows help.
- -v or --version shows version.
Setting up simulation is the first phase after launching the simulation, when *"Setting up"* text shows up in the console window. During setup, those commands can be called:
- auto pause <enabled/disabled:enable> which enables or disables auto pause after one second of inactivity. For example: "`auto pause enabled`".
- begin runs simulation, see third phase.
- end exits simulation.
- help shows help.
Starting simulation - during this phase virtual network is created and scenario file is read. Scenario file can contain settings for simulation (for example: auto pause setting, simulation time limit, etc.) and settings for each node such as node MCU frequency, transmission bitrate, SSID, etc. Special case is auto pause setting, if auto pause was enabled or disabled before this phase, auto pause setting from scenario file will be ignored.
During simulation it can be controlled by the following commands:
- resume - Resumes simulation.
- resume for <ulong:time> - Resumes simulation for specified simulation time in nanoseconds.
- pause - Pauses simulation.
- auto pause <enabled/disabled:enable> which enables or disables auto pause after one second of inactivity.
- ping <uint:source> <uint:destination> <uint:timeout[1000, 127500]> <uint:load[0, 500]> - Pings specified node with "destination" MAC address from module with "source" MAC address.
- send <uint:from> <uint:to> <message> - Invokes message send from node with "from" MAC address to module with MAC "to" address.
- net scan <uint:node> <uint:timeout[500,10000]> - Invokes network scan on node with "node" MAC address with "timeout" in ms.
- connect <uint:from> <uint:to> - Invokes connection of node with MAC address "from" to node with MAC address "to".
- disconnect <uint:from>- Invokes node disconnection with MAC address "from".
- disconnect request <uint:gateway> <uint:node> - Invokes disconnection of "node" by "gateway" node.
- network drop <uint:gateway> <-f:forced drop> - Invokes network drop by "gateway" node.
- print table <uint:node> <rt/idt/fidt/oidt/dhcpt/wf/of:table_type> - Prints out table or buffer of type "table_type" of node with MAC address "node". For example: print table 1 rt.
- end - Turns off simulation and exits application. This must be called before closing simulation to correctly save log file.
- help - Shows help.

How to view documentation

Download and install doxygen to your device.
When you use:
- Windows - run makeDoc.bat file, it will create documentation to html directory and opens it. When you have already generated documentation directory (html), you can view it by opening index.html file in that directory.
- Linux or Mac - run doxygen.exe in console in folder to generate documentation. Open file in html/index.html

Used libraries and codes

RapidJSON library for JSON parsing in C++
Date library for C++
Base64 small library for Base64 encoding and decoding in C++
ConsoleTextColor small library for coloring text in console for windows and linux in C++

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.