Help — CupCarbon Simulator

🚀 Getting started

Install Java 17 or newer (adoptium.net) and, for IoT node scripts, Python 3 on the PATH.
Download the CupCarbon package of your platform (Installation Guide), unzip, and double-click its launcher (cupcarbon_win.bat, cupcarbon_macm.command/cupcarbon_macx.command or cupcarbon_linux.sh) — it starts CupCarbon from its own folder so the utils/ resources are found.
Create a project: File → New project. A project is a folder containing your nodes, scripts, GPS routes, agentic workflows and results.
Set the executor paths once (Python/Julia/Node) via the executor configuration button if scripts don't start.

🗺️ Interface & map

The map (OpenStreetMap tiles or offline backgrounds via the Map menu) is where you build your network. Useful interactions:

Action	How
Add objects	press a number key (e.g. `2` for sensors) then click the map — or use console commands like `add iot 25.3020 55.4855`
Select	click an object, or drag a rectangle; `i` inverts the selection
Change an IoT node's icon	select it and press `j` — an icon gallery opens
Radio / sensor radius	`;` / `,` and `(` `)` on the selection
Duplicate	`c` on the selection
Map background	Map menu: OSM Light/Dark, offline backgrounds (work without internet)

📡 IoT nodes

IoT nodes run external Python scripts (or Julia/Node). Assign a script to a node from the node panel or the Program editor (toolbar), write your logic with the cup_* functions, then run the IoT simulation. The Program editor has Python syntax highlighting, auto-indentation (Tab = 4 spaces, tabs highlighted in red, one-click Tabs→Spaces fix), the full function list with per-function help and examples, and ready-made example buttons.

🐍 Python cup_* functions

Start your script with from cup_functions import * (for IDE completion — CupCarbon injects the real implementations at simulation start).

Category	Functions
Display	`cup_print`, `cup_mark`, `cup_unmark`, `cup_pic`, `cup_visible`, `cup_alert`, `cup_message`
Mobility	`cup_move`/`cup_moveto`, `cup_speed`, `cup_rudder_angle`, `cup_routewait`, `cup_routestop`, `cup_routego`, `cup_route`
Reading	`cup_getid`, `cup_getname`, `cup_getx`, `cup_gety`, `cup_getxy`, `cup_ismarked`, `cup_dsensor`, `cup_getmessage`, `cup_getaction`
Messaging	`cup_send`, `cup_read` (node ↔ node)
Agentic AI	`cup_toagent(txt, cupid)`, `cup_fromagent(cupid)` (node ↔ workflows)
Control	`cup_wait`, `cup_stopsimulation`

from cup_functions import *

while True:
    cup_mark()
    cup_toagent('hello from node', 32)
    answer = cup_fromagent(32)
    cup_print(answer)
    cup_unmark()
    cup_wait(1)

▶️ Simulations

IoT simulation (toolbar ▶ IoT): runs each IoT node's external script in real time — this is the mode used with the cup_* functions and the agentic workflows.
WSN simulation: the discrete-event simulator for SenScript nodes (radio models ZigBee/WiFi/LoRa, interference, energy and battery models, results in results/wisen_simulation.csv).
Agentic workflows run independently with their own Run/Stop buttons — see the Agentic AI page.

💻 Consoles & remote control

Console button: the output console (System.out left, System.err right) — now non-blocking even with very long logs.
Command button: the command console — type commands like add iot 25.3020 55.4855, list devices, sim iot start… It is also an MQTT gateway with secure random per-session topics: click Copy Topic and drive CupCarbon from any browser with the Web Console, CupCarbon Studio or the Web Workflow Editor.
Full command list with examples: the Command Reference.

🤖 Agentic AI in one minute

Open the workflow editor (🤖 toolbar button, project required) → New.
☰ Nodes → add Chat Trigger, AI Agent, Chat Response; connect them.
Click API Keys and paste your Anthropic or OpenAI key (stored locally).
Run → chat with your network in the panel bottom-right.

Full details, node list and the CupCarbon bridge on the Agentic AI page.

🛠️ Troubleshooting

Symptom	Fix
Map tiles don't load / project slow to open	No internet or blocked tile server: switch to an offline background (Map menu). Tile requests now time out after a few seconds.
Python `TabError`	Mixed tabs/spaces: tabs are highlighted in red in the editor — click Tabs → Spaces.
AI Agent answers "no rule matched"	The LLM wasn't reached: check the provider on the node, the API key (API Keys dialog; env vars take priority) and the console for the exact error.
IoT scripts don't start	Check the executor paths (Python must be on the PATH) and that a script is assigned to each IoT node.
Web pages can't reach CupCarbon	Open the Command console first (it activates MQTT), re-copy the topic (it changes at every launch), and try the `ws://…:8083` broker endpoint if `wss://…:8084` is blocked.

📖 Simulator Help