Stage 2 · First Simulation

Quickstart

Launch the daemon, connect a simulator, send a message, and watch it travel through NSB — all in under 10 minutes.

← Back to Get Started Browse Documentation

Estimated time: ~10 minutes

Python · C++

Message Round-Trip

Application Client

NSBAppClient

NSB Daemon

Routes & queues

Mock Simulator

NSBSimClient

Prerequisite: Completed Get Started — NSB installed and verified. Complete that guide first if you haven't already.

What You Will Build

A complete message round-trip through NSB — from your application, through the daemon, through a mock simulator, and back.

Application Client

NSBAppClient — sends payload

NSB Daemon

Routes and queues messages

Mock Simulator

NSBSimClient — fetches, posts back

NSB Daemon

Delivers to destination

Application Client

NSBAppClient — receives payload

Create Configuration

Save the following as config.yaml in your working directory.

yaml

---
system:
  daemon_address: 127.0.0.1   # address where the NSB daemon runs
  daemon_port: 65432           # port the daemon listens on
  mode: 0                      # 0 = PULL (clients request messages)
  simulator_mode: 1            # 1 = Per-Node (each node has its own SimClient)

database:
  use_db: false                # false = direct transmission, no Redis needed

Field

Value

mode: 0

PULL

Clients request messages — simplest mode

simulator_mode: 1

Per-Node

Each node has its own simulator client

use_db: false

disabled

Payloads sent directly — no Redis needed

Redis is optional. For this Quickstart, use_db: false transmits payloads directly through NSB without storage. Redis can be enabled later for large-payload scenarios. Database Settings →

See all configuration fields →

Start the NSB Daemon

Open Terminal 1 and launch the daemon with your config file.

From the build directory:

bash

./build/nsb_daemon config.yaml

Or from the install path:

bash

/[your/install/path]/nsb/bin/nsb_daemon config.yaml

The daemon starts up and begins listening for connections. Keep this terminal open.

Start the Mock Simulator

Open Terminal 2. This mock simulator fetches payloads from NSB and passes them straight through — no real network simulator needed.

simulator.py

python

import nsb_client as nsb
import time

# Connect to NSB as a simulator client
sim = nsb.NSBSimClient("node0", "127.0.0.1", 65432)
print("Mock simulator ready — waiting for messages...", flush=True)

while True:
    entry = sim.fetch(timeout=1)
    if entry:
        src = entry.src_id
        dst = entry.dest_id
        payload = entry.payload

        print(f"Simulating: {src} -> {dst}, payload: {payload}", flush=True)

        # For this quickstart, pass straight through.
        # In a real simulator, you would route via ns-3 or OMNeT++ here.
        sim.post(src, dst, payload)
        print("Posted payload as delivered", flush=True)
        break
    time.sleep(0.1)

fetch(timeout=1) checks for a message and returns immediately if none is available yet — it does not mean the simulator gives up after one second. The surrounding loop keeps checking until a message arrives, so you can start the application whenever you are ready.

bash

python3 simulator.py

Start the simulator before the application so it is ready to fetch() when messages arrive. Once the daemon and simulator are running, you can start the application whenever you are ready — there is no need to launch it immediately.

Run the Application Client

Open Terminal 3. This sends a payload and waits to receive it back.

app.py

python

import nsb_client as nsb
import time

# Connect to NSB as an application client
app = nsb.NSBAppClient("node0", "127.0.0.1", 65432)

# Send a payload through the mock simulator
app.send("node0", b"Hello from node0!")
print("Sent payload")

# Poll for a response
print("Waiting for response...", flush=True)

while True:
    entry = app.receive()
    if entry:
        print(f"Received: {entry.payload} from {entry.src_id}", flush=True)
        break
    time.sleep(0.1)

bash

python3 app.py

Run in this order:

Terminal 1

bash

./build/nsb_daemon config.yaml

Terminal 2

bash

python3 simulator.py

Terminal 3

bash

python3 app.py

Confirm Success

Check these outputs match before continuing.

Terminal 2 (Simulator)

text

Mock simulator ready — waiting for messages...
Simulating: node0 -> node0, payload: b'Hello from node0!'
Posted payload as delivered

Terminal 3 (Application)

text

Sent payload
Waiting for response...
Received: b'Hello from node0!' from node0

Message sent by application

Message fetched by simulator

Message delivered (posted back to daemon)

Message received by application

Two-Node Example (Python)

A complete round-trip where node0 sends to node1, and node1 replies back. This shows the full Per-Node simulator mode in action.

Node 1 waits for you. Node 1 waits for an incoming message instead of exiting when no message is immediately available. This means you can start Node 1 first and start Node 0 later — you do not need to coordinate their startup timing.

app_node0.py

python

import nsb_client as nsb
import time

app = nsb.NSBAppClient("node0", "127.0.0.1", 65432)
app.send("node1", b"Hello, node1!")
print("[node0] Sent message")

print("[node0] Waiting for reply...", flush=True)

while True:
    entry = app.receive()
    if entry:
        print(f"[node0] Received reply: {entry.payload}", flush=True)
        break
    time.sleep(0.1)

app_node1.py

python

import nsb_client as nsb
import time

app = nsb.NSBAppClient("node1", "127.0.0.1", 65432)

print("[node1] Waiting for message...", flush=True)

while True:
    entry = app.receive()
    if entry:
        print(f"[node1] Received: {entry.payload}", flush=True)
        app.send(entry.src_id, b"Hello back, node0!")
        print("[node1] Sent reply", flush=True)
        break
    time.sleep(0.1)

simulator.py — Per-Node, handles both nodes

python

import nsb_client as nsb
import time

sim0 = nsb.NSBSimClient("node0", "127.0.0.1", 65432)
sim1 = nsb.NSBSimClient("node1", "127.0.0.1", 65432)

simulators = [sim0, sim1]
messages_processed = 0

print("[sim] Mock simulator ready — waiting for messages...", flush=True)

while messages_processed < 2:
    for sim in simulators:
        entry = sim.fetch(timeout=0)
        if entry:
            print(f"[sim] Routing {entry.src_id} -> {entry.dest_id}")
            time.sleep(0.1)
            sim.post(entry.src_id, entry.dest_id, entry.payload)
            messages_processed += 1

    time.sleep(0.1)

Run the example — use four terminals:

Start the daemon first, then the simulator. You can start Node 1 before Node 0. Node 1 waits for its incoming message, so you do not need to start Node 0 immediately.

Terminal 1 — NSB Daemon

bash

./build/nsb_daemon config.yaml

Wait for the daemon to report that it is listening.

Terminal 2 — Per-Node Simulator

bash

python3 simulator.py

Wait for the simulator to print "Mock simulator ready".

Terminal 3 — Node 1

bash

python3 app_node1.py

Node 1 prints "[node1] Waiting for message..." and stays alive. Take your time before starting Node 0.

Terminal 4 — Node 0

bash

python3 app_node0.py

Start Node 0 whenever you are ready. It sends to Node 1, triggering the full round-trip.

Expected output:

NSB itself may print additional INFO or WARNING log lines. The lines below are the important application-level output — your terminals will not be limited to only these lines.

Terminal 2 (Simulator)

text

[sim] Mock simulator ready — waiting for messages...
[sim] Routing node0 -> node1
[sim] Routing node1 -> node0

Terminal 3 (Node 1)

text

[node1] Waiting for message...
[node1] Received: b'Hello, node1!'
[node1] Sent reply

Terminal 4 (Node 0)

text

[node0] Sent message
[node0] Waiting for reply...
[node0] Received reply: b'Hello back, node0!'

Application called send() — NSB created a SEND message and transmitted it to the daemon. The daemon queued the payload, ready for the simulator to pick up.

Simulator called fetch() — the daemon responded with the queued payload. In a real integration, this is where ns-3 or OMNeT++ would route the payload through a simulated network topology with configurable latency, loss, and bandwidth.

Simulator called post() — NSB marked the payload as delivered. The daemon queued it for the destination application client.

Application called receive() — NSB returned the delivered payload. That complete loop — send → fetch → post → receive — is one NSB message round-trip.

Architecture Overview Message Flow Payload Lifecycle

Continue Learning

Explore the full NSB documentation and tutorials.

Learn NSB Fundamentals

Understand the core concepts, architecture, and how NSB components work together.

Explore Fundamentals

Configure NSB

Learn how to configure NSB to fit your simulation requirements and environment.

Explore Configuration

Develop with NSB

Use NSB APIs and libraries to build applications and simulators.

Explore Development

Integrate Simulators

Integrate NSB with popular network simulators and frameworks.

Explore Integrations

Tutorials & Examples

Step-by-step tutorials to help you get hands-on with NSB.

Explore Tutorials

Advanced Topics

Deep dive into advanced features and backend implementations.

Explore Advanced

Need Help?

Get assistance and find answers to common questions.

Troubleshooting Guide

Common issues, error messages, and step-by-step solutions.

View Troubleshooting

Frequently Asked Questions

Answers to frequently asked questions about NSB concepts and usage.

View FAQ

You're all set

Explore the full documentation

Dive deeper into architecture, configuration, API references, and real simulator integrations.

Browse Docs