Frequently Asked Questions

Here you will find solutions to common questions and default behaviors in the OOCSI system.

Why was my client rejected by the server?

When a client connection terminates abruptly (e.g., stopping a script without disconnecting cleanly, power-cycling a microcontroller, or refreshing a web browser), the server may hold the previous connection token until its 120-second inactivity timeout expires. If you attempt to connect with the identical name during this period, the server rejects the connection to protect against handle hijacking.

The Solution: Append hash characters (####) to your client name (e.g., controller_#### or sensor_node_####). The server automatically replaces each # with a random digit upon connection, ensuring an instantly unique name and zero connection collisions.

Why is my client not connecting to the server?

Local vs. Remote: If running locally, verify that your server container or JAR is actively running. If connecting to a remote server, check your Internet or local WiFi connection.
Port Restrictions: OOCSI uses port 4444 for native TCP sockets (Java, Python, C++) and port 9000 for WebSockets (ws://<host>:9000/ws). School, university, or corporate firewalls sometimes block non-standard ports like 4444. Try testing on a personal hotspot or asking your network administrator.

Why does my web browser client fail to connect?

If your website is hosted on an HTTPS domain (e.g., https://myproject.com), modern browsers block insecure WebSocket connections (ws://) due to mixed-content security policies.

Fix: Use wss:// (WebSocket Secure) with a valid SSL/TLS certificate configured on your server reverse proxy (e.g. Nginx or Caddy).
Endpoint: Ensure your WebSocket URL points to the /ws path (e.g. wss://demo.oocsi.net/ws).

Why can my client not receive its own messages to a channel?

sequenceDiagram
    autonumber
    actor ClientA as Client A
    participant Broker as OOCSI Server
    actor ClientB as Client B (Subscriber)

    rect rgb(255, 240, 240)
        Note over ClientA,ClientB: Case 1: Standard Channel (Self-Echo Blocked)
        ClientA->>Broker: Send to "kitchen" {"light": true}
        Broker->>ClientB: Forwarded to Client B
        Broker--xClientA: Omitted (Prevents feedback loop!)
    end

    rect rgb(240, 255, 240)
        Note over ClientA,Broker: Case 2: Echo Channel (Round-Trip Test)
        ClientA->>Broker: Send to "echo" {"ping": 123}
        Broker->>ClientA: Bounces back directly to Client A handle!
        Note over ClientA: Measures round-trip time (<50ms)
    end

By default, the OOCSI server prevents messages from echoing back to the client that sent them, even if that client is subscribed to the destination channel. This design prevents infinite feedback loops and duplicate event processing.

If you specifically want to test message reception or loop back data to yourself, send the message to the special built-in echo channel:

// Java / Processing: Message sent to echo channel is reflected back to the sender
oocsi.channel("echo").data("test_value", 42).send();

# Python
oocsi.send("echo", { "test_value": 42 })

// JavaScript (oocsi-web.js)
OOCSI.send("echo", { test_value: 42 });

// ESP32 (Embedded C++ / Arduino)
oocsi.newMessage("echo");
oocsi.addInt("test_value", 42);
oocsi.sendMessage();

Why can my message not be received by other clients?

Check these common checklist items:

Case Sensitivity: Channel names are case-sensitive. LivingRoom and livingroom are two completely different channels.
Active Subscription: Ensure the receiving client calls subscribe() before messages are sent.
Event Handler Registration: Ensure the receiving client attached a callback function or handler to the subscription.
Different Servers: Ensure both clients are connected to the exact same server address and port.

Why am I receiving a LOT of messages (that don’t stop) although only one was sent?

Usually, the message was delivered only once, but your client code processes it repeatedly on every frame. This happens when message handling code is inadvertently placed inside an unthrottled loop (e.g., inside Processing’s draw() loop or an Arduino loop() without event-driven gating). Move message processing into a dedicated event callback handler.

Why am I receiving several messages with missing keys?

Avoid sending attributes individually:

// AVOID: Sends three separate, incomplete messages
oocsi.channel("sensors").data("temp", 21).send();
oocsi.channel("sensors").data("hum", 55).send();
oocsi.channel("sensors").data("light", 300).send();

Always bundle related data into a single message:

// RECOMMENDED: Sends a single atomic message with all keys
oocsi.channel("sensors").data("temp", 21).data("hum", 55).data("light", 300).send();

What characters are allowed in client and channel names?

Allowed Characters: Letters (a-z, A-Z), digits (0-9), hyphens (-), underscores (_), periods (.), and colons (: for password channels).
Length Limit: Maximum 200 characters.
Reserved Names: The server reserves system identifiers: SERVER, OOCSI_events, OOCSI_connections, OOCSI_channels, OOCSI_clients, and OOCSI_metrics. Clients cannot register using these names or write directly to them.