CupCarbon Klaines

CupCarbon Klaines: A Simulator for Smart City, IoT and
Wireless Sensor Networks with Agentic AI

The CupCarbon Project — cupcarbon.com

Version Klaines 8.0, 2026 — Free software (GNU GPL)

Abstract — CupCarbon is a Smart City and Internet of Things Wireless Sensor Network (SCI-WSN) simulator. Networks are designed directly on an OpenStreetMap city map and simulated with a discrete-event engine, taking into account radio propagation, interference, mobility, energy consumption and the urban environment (buildings). The Klaines generation introduces agentic artificial intelligence: a visual, n8n-style workflow editor in which IoT nodes exchange data with AI agents connected to real large language models (Anthropic Claude, OpenAI), together with Python-programmable nodes (cup_* functions), MQTT remote control from any browser, and native packages for every platform. CupCarbon is used for research, engineering and education.

1. Overview

Table 1 — CupCarbon Klaines at a glance.
Property	Value
Current version	Klaines 8.0 (2026)
License	GNU General Public License (free and open)
Platforms	Windows x64, macOS (Apple Silicon & Intel), Linux (x64 & ARM)
Requirements	Java 17 or newer; Python 3 for IoT node scripts
Node programming	Python (`cup_*` API), SenScript, Julia, Node.js
Interoperability	MQTT (ws/wss/tcp/ssl), Anthropic & OpenAI APIs, OpenStreetMap, Overpass

2. Simulation features

Discrete-event WSN engine

Faithful simulation of sensor networks: radio communication (ZigBee, WiFi, LoRa), energy and battery models, sensor events, fault injection and result logging.

City-scale environment

Design on real OpenStreetMap maps; buildings are imported from Overpass and used in the radio visibility model, which recomputes ranges live while nodes move.

Mobility

GPS routes, speeds and mobile nodes; trajectories designed on the map and followed during the simulation.

Python-programmable nodes

Each IoT node runs a real external Python script through the cup_* API (29 functions: mobility, sensing, messaging, display) with a syntax-highlighted editor and per-function help.

3. Agentic AI workflows

The Klaines generation embeds a visual workflow editor inspired by n8n. Workflows are built from nodes (triggers, logic, MQTT, AI) connected on a canvas, run continuously and independently from the simulation, and exchange messages with the sensor nodes through cup_toagent() / cup_fromagent(). The AI Agent node connects to Anthropic Claude or OpenAI (user-provided API key, with an offline rule-based fallback and conversation memory), enabling chatbots and autonomous decision loops that drive the network. Workflows use the n8n item data model with JavaScript {{ $json }} expressions evaluated in a fully sandboxed engine. Read the Agentic AI documentation →

4. Remote control and web tools

CupCarbon can be driven from any browser through MQTT with secure per-session topics: a web console (all simulator commands), CupCarbon Studio (console + workflow exchange with visual preview), a full web workflow editor, and the command reference with three examples per command.

5. Download and installation

One package per platform; each contains the application, its launcher and the runtime resources. Install Java 17+ (adoptium.net) and Python 3 (python.org), unzip, launch. The installation guide details every step, per platform.

Table 2 — Distribution packages of CupCarbon Klaines 8.0. Choose the package matching your operating system and processor architecture.
Platform	Package	Launcher
Windows (x64)	`cupcarbon_windows.zip`	`cupcarbon_win.bat`	Download
macOS — Apple Silicon (M1–M4)	`cupcarbon_macos_m.zip`	`cupcarbon_macm.command`	Download
macOS — Intel	`cupcarbon_macos_x.zip`	`cupcarbon_macx.command`	Download
Linux x64	`cupcarbon_linux_x.zip`	`cupcarbon_linux.sh`	Download
Linux ARM	`cupcarbon_linux_m.zip`	`cupcarbon_linux.sh`	Download

Which macOS package? Apple menu → About This Mac: “Chip Apple M…” → Apple Silicon package; “Processor Intel…” → Intel package.

6. Documentation and teaching material

Installation guide — step-by-step, per platform.
Simulator help — interface, IoT nodes, Python functions, simulations, consoles.
Tutorials — first program, agentic AI, remote control, MQTT.
User Guide for IoT & Digital Twin (PDF)
User Guide for WSN & SenScript (PDF)
Video tutorials (YouTube) — including the SenScript tutorial.
CupCarbon & ESP32/MQTT integration
Source code — for developers and researchers.

7. Publications — how to cite

If you use CupCarbon in academic work, please cite the reference paper:

K. Mehdi, M. Lounis, A. Bounceur and T. Kechadi, “CupCarbon: A Multi-Agent and Discrete Event Wireless Sensor Network Design and Simulation Tool”, 7th International ICST Conference on Simulation Tools and Techniques (SIMUtools'14), Lisbon, Portugal, 2014.
A. Bounceur et al., “CupCarbon-Lab: An IoT Emulator”, IEEE Consumer Communications & Networking Conference (CCNC), Las Vegas, USA, 2018.

@inproceedings{cupcarbon2014,
  title     = {CupCarbon: A Multi-Agent and Discrete Event Wireless Sensor
               Network Design and Simulation Tool},
  author    = {Mehdi, Kamal and Lounis, Massinissa and Bounceur, Ahcene
               and Kechadi, Tahar},
  booktitle = {7th International ICST Conference on Simulation Tools
               and Techniques (SIMUtools'14)},
  address   = {Lisbon, Portugal},
  year      = {2014}
}