CherrySim

CherrySim uses the codebase of BlueRange Mesh and provides a SoftDevice abstraction layer that simulates Bluetooth connections, advertising, flash access and much more. It gives the possibility to debug, develop and simulate multiple BlueRange Mesh nodes on a development PC.

We are developing and debugging most new features using CherrySim which is a real time saver and swiss army knife. You will be able to do implement most of your application logic in the simulator with the ability to mock away drivers. If you are developing with BlueRange Mesh you should consider using the simulator for your day-to-day development.

The build environment can be set up by following the instructions under Building with CMake.

See here for a guide how to build the Simulator.

CherrySim uses a header file SystemTest.h that is force-included before all other header files to be able to abstract the SoftDevice. All SoftDevice calls are implemented in a way to closely mock the functionality of a real SoftDevice. For everything that uses the radio, such as advertising or connections, a simplified simulation is used that calculates the distances between nodes and simulates packet loss.

CherrySim works with only one instance and is able to simulate many instances of BlueRange Mesh. Hence BlueRange Mesh must be written in a way that the code itself has no state variables. No global or functional static variables are allowed. Every variable that needs to be saved from one function call to the next needs to be a part of class since CherrySim creates instances of classes for every node. The GlobalState.cpp is used to store the whole state of a node and CherrySim switches the pointer to the currently simulated node for each simulation step.

CherrySim gives each node a different serial numbers starting at BBBBB and incrementing. Every forth byte of the node key, starting with the first byte is equal to the serial number index + 1. So for example, BBBBB has the node key 01:00:00:00:01:00:00:00:01:00:00:00:01:00:00:00, BBBBC has the node key 02:00:00:00:02:00:00:00:02:00:00:00:02:00:00:00 and so on. By default, all nodes have the same networkId and networkKey so that they are in the same mesh network. If this is not desired, the simulated UICR can be overwritten or the nodes can be enrolled using the standard enrollment command. Default featuresets are given to each node but the featureset can also be individually configured for each node.

Open http://localhost:5555/ in a web browser while the simulator is running and simulating.

The Webserver serves the FruityMap for visualization and has some endpoints that serve dynamic JSONs that reflect the current mesh state. Be aware that the visualization shows the GAP connections and not the MeshConnections. This is an important difference. If all MeshConnections are handshaked, in a stable state and if there are no implementation errors, these visualizations match.

The connections are presented using arrows which originate from the central and point to the peripheral. The black dots represent the connection master bits. RSSI / globalConnectionId is shown for each connection while the nodes show "nodeId / clusterSize".

The LEDs are also visualized but all LED changes are mapped to a single one.

CherrySim is great for debugging issues that only arise with multiple nodes. As you are able to add nodes with different featuresets, you can easily simulate this network and debug the node interaction.

CherrySim by default supports stdio for input and output and you are able to chose a terminal and start entering commands right within the console. This is however quite limited and you are not able to easily connect to multiple terminals at the same time. Therefore, we have implemented SocketTerm which allows you to connect to the simulator by using a TCP socket e.g. by using a telnet client or other software such as a gateway.

By default, CherrySim listens on port 5556. To open a connection, e.g. use telnet localhost 5556. This is very flexible as it also allows you to connect a custom gateway to the simulation or multiple gateways at the same time as CherrySim is also able to simulate multiple networks at the same time. It is a good idea to start CherrySim with the commandline argument disableStdio, e.g. cherrysim_runner.exe disableStdio as this will considerably improve the performance.

After the session was opened, you will be informed with a message of type sim_socket_connect that you are now connected. The first thing you have to do is to select a terminal by using sim term [terminalId] to connect to the terminal of a node. The terminal id of a node is equal to nodeIndex + 1 (the default node id), see the documentation on featureset simulation on how the node index is assigned. If you do not change the node id (e.g. via enrollment) after the simulator starts, then the terminal id and node id will be the same. Additionally, the terminal id of a node will stay the same during the whole simulation and is not affected by enrollments.

A response of type sim_term_changed will inform you if the simulator was able to switch to the terminal or if it e.g. does not exist. Depending on the featureset, the node will have its terminal configured to JSON or PROMPT mode. Be aware that you will not get any echo-back of what you are typing as the SocketTerm is intended for process to process communication. Your telnet client (e.g. Putty) will however have an option to toggle local echo if necessary.

You are now connected to the terminal of the specified node and you are free to open more clients to interact with other nodes at the same time. Only a single client can be connected to the terminal of a single node.

CherrySimTester is used to write automated tests against the mesh. Typically a test will first set up a mesh network with a few nodes, possibly with different featuresets. Afterwards, it might wait until they are clustered and then send some terminal commands. Next, the simulation might wait for some message to be received so that the test is considered passing. Have a look at the available tests under <fruitymesh>/cherrysim/test to get a better understanding.

Command line arguments of the cherrySim_tester executable:

Additionally the usual gtest flags can be used:

Prior to the implementation of SimulateUntilRegexMessageReceived we had to simulate for exact message hits. However, this was not always practical. For example, if the battery measurement is queried it is not helpful to only accept a specific battery measurement, instead it is important to write a google unit test that makes sure that any battery measurement is returned. This was made possible with the addition of RegexMessages.

Two very nice online resources to test if a given regex matches with a message are the following: https://regex101.com/ and https://regexr.com/

Noteworthy: Both "{" and "}" (occurring in JSONs) have to be escaped because they are special regex chars. The regex escape character itself has to be escaped as it is placed in a C-String-Literal, thus a "{" becomes "\\{".

In some cases, we want to write a test where we want to check if a certain exception has occurred or not even though we have disabled it, e.g for writing a test to check if our code throws an IllegalArgumentException, if we provide a malformed string buffer to our Logger::ParseEncodedStringToBuffer(..) method. Example implementation could be

In our example above, we first disabled the IllegalArgumentException. The simulator will then start to accumulated the exceptions for one simulation step and we can later check if an IllegalArgumentException was thrown in that simulation step by calling CheckExceptionWasThrown(..).

This should be used instead of ASSERT_THROW as a simulator exception will leave the firmware code and simulation step exceptionally, thereby leaving the simulation in an undefined state. If we disable the exception, we can however safely continue the simulation.

Some of the simulate functions also have a "stepCallback" parameter. This is a std::function which, if provided, is called before each simulation step. This is for example used to constantly fill the queues in tests.

Multiple nodes in the mesh only guarantee that the passed time is the same for all of them on average (plus a small bias). To make sure that we are able to handle such behaviour, "jittering" was implemented into the simulator. Jittering can be enabled by setting simulateJittering to true inside the configuration. Once it is enabled, there is on average a 50% chance that a simulated node is not simulated in one simulation step. In addition to this, nodes that have been simulated more rarely than others have a higher probability to be executed, and vice versa. This generates more randomness and closeness to the real world behaviour.

A custom Random Number Generator (RNG) is used in the simulator. Originally the implementation of it comes from the "BrotBoxEngine", see: https://github.com/Brotcrunsher/BrotBoxEngine/blob/master/BrotBoxEngine/BBE/MersenneTwister.h .

The use of a RNG is very important in the simulator. It must have two properties:

The second point is unfortunately not guaranteed by the std::mt19937 and the std::distributions implementation. Although the same compiler always generates the same output, the same is not true for different compilers. In practice we noticed that MSVC generated different results compared to GCC when using the STL implementation.

The simulator implements a simple stack overflow detection mechanism, found in the "StackWatcher". One can set the simulated "stack base" (which is the simulated start of the stack of a device) by creating the RAII type "StackBaseSetter". Most functions in the SystemTest.h then check if the current stack, minus the latest value in the StackBaseSetter is larger than some threshold. If it is, an exception is thrown.

The simulator is able to store the flash of all nodes into a file, making it easier to reuse a simulated mesh as all nodes are enrolled in the proper network and all other configurations are kept. To use this feature, set storeFlashToFile to any path you wish. If this attribute is not the empty string, the simulator stores the flash in this file. If the given file exists, the simulator loads the configuration on startup.

The simulator supports simulating an arbitrary amount of different featuresets. To add a new featureset to the list of used featuresets, add it to the list inside CherrySim::PrepareSimulatedFeatureSets().

One simulated featureset is a struct object that contains a set of function pointers. See FeaturesetPointers. All these function pointers should not be called directly, but via the macros that are used on real hardware instead.

The simulator makes sure that a printed JSON has a valid JSON format by parsing it once it is fully logged out. To see how this is done, check out Logger::log_f.

The simulator is able to store and load its configuration in JSON format. To see how this is done, have a look at void to_json(nlohmann::json& j, const SimConfiguration& config); and void from_json(const nlohmann::json& j, SimConfiguration& config);. These two functions are then used to load and store the configuration. In practice this is for example used in the CherrySimRunner to load the MeshGwCommunicationConfig.json which in turn is used to properly configure the simulator for our SystemTests. Have a look for MeshGWCommunicationConfig.json inside the CherrySimRunner.cpp to see how this is done.

The simulator supports the use of special simulator commands. These commands all start with "sim ". They don’t necessarily have a node as its execution target but are rather commands that have the simulator itself as target. Additionally, sim commands are treated differently as other messages as in they don’t simulate the same restrictions for the length of the command. In fact a sim command can be arbitrarily long. Have a look at the Terminal.cpp and search for "sim " (with the space at the end and the quotation marks).

If CherrySim has trouble loading some files (mostly with the integrated webserver) you can try to specify the working directory in an environment variable CHERRYSIM_WORKDIR without a trailing / like this: /path/to/cherrysim.

Nordic allowed us in their forums to use their headers in our simulator as long as it is used to simulate a Nordic Integrated Circuit. See: https://devzone.nordicsemi.com/f/nordic-q-a/57615/legal-issue-using-nordic-sdk-code