CupCarbon Klaines Tutorials

🚀 Installation Guide

Install Java 17+ and Python 3, download the CupCarbon Klaines package of your platform, unzip and double-click its launcher (cupcarbon_win.bat, cupcarbon_macm.command / cupcarbon_macx.command, or cupcarbon_linux.sh).

Complete installation instructions: View Installation Guide

⌨️ CupCarbon Python Commands — the cup_* functions

IoT nodes are programmed in Python with the predefined cup_* functions. Start your script with the import line (it gives you auto-completion in any IDE; CupCarbon replaces it with the real implementations when the simulation starts):

from cup_functions import *

1. Print

Display any message next to the executing node:

cup_print('Hello World!')
cup_print('Temperature:', 25.4, 'C')

2. Mark / Unmark

cup_mark()
cup_unmark()

3. Move

Move the executing node to a GPS location (longitude, latitude):

cup_move(50.002, 21.344)

4. Get information

Read functions return typed values directly — no more input():

node_id = cup_getid()       # int
name    = cup_getname()     # str
x, y    = cup_getxy()       # floats (longitude, latitude)
x       = cup_getx()
y       = cup_gety()
marked  = cup_ismarked()    # bool
detect  = cup_dsensor()     # bool

5. Node ↔ node messaging

cup_send('hello')        # broadcast to the radio neighbors
cup_send('data', 3)      # send to node 3
msg = cup_read()         # blocking receive

Coming from an older version? The historical style (def cup(com): print(com, flush=True) then cup("mark") and input()) still works — the cup_* functions are a cleaner layer on the very same protocol. Full list with per-function help and 3 examples each: press the Help button in CupCarbon's Program editor, or see the function table.

🧪 Example: Alternating Display

from cup_functions import *

while True:
    cup_print('Hello ')
    cup_mark()
    cup_wait(1)
    cup_print('World!')
    cup_unmark()
    cup_wait(1)

Assign this script to an IoT node (Program editor → Save, then set it on the node), and click ▶ Run IoT Simulation. The editor highlights Python syntax, converts tabs to spaces automatically, and its side panel inserts any cup_* function with a double-click.

🤖 New: talk to the Agentic AI workflows

Two functions connect your node scripts to the visual AI workflows (🤖 toolbar button):

from cup_functions import *

while True:
    cup_toagent('temperature 42', 32)   # fires CupCarbon Read triggers (cupid 32)
    answer = cup_fromagent(32)          # waits for a CupCarbon Send node (cupid 32)
    cup_print(answer)
    cup_wait(2)

Build the workflow side visually: CupCarbon Read → AI Agent (Claude/OpenAI) → CupCarbon Send, and your simulated node now asks an LLM what to do. Chatbots, MQTT pipelines and more on the Agentic AI page.

🌐 New: remote control from the browser

In CupCarbon, click Command (opens the command console) then Copy Topic.
Open the CupCarbon Studio or the Web Console, paste the topic, Connect.
Type commands (add iot 25.3020 55.4855, sim iot start...) — full list in the Command Reference.

The topics are random per session, so only someone with your topic can drive your simulator.

📡 MQTT for IoT Projects

For custom Python MQTT clients inside your node scripts:

pip install paho-mqtt     # or: pip3 install paho-mqtt

No code needed for many cases: the agentic workflows include ready-made MQTT Trigger and MQTT Publish nodes (ws/wss/tcp/ssl, broker presets, automatic port selection).

🎉 Now you can use CupCarbon, enjoy!