Support & Troubleshooting

Although OOCSI is designed to be lightweight and beginner-friendly, networking issues can occasionally occur during prototyping. If you encounter an issue, follow this structured diagnostic guide to identify and resolve the problem.

---

⚡ The Golden Rule of Client Naming

Always append hash characters (####) to your client handle!

If two clients attempt to connect with the exact same handle (or if your client crashes and reconnects before the 120-second server timeout cleans up the old session), the server will reject the new connection.

When you include hashes in the name (e.g., sensor_node_#### or web_ui_####), the OOCSI server automatically replaces each # with a random digit upon connection. This guarantees a unique handle and prevents reconnect collisions.

---

Troubleshooting Matrix

Symptom	Probable Cause	Solution
Connection rejected	Client handle already in use, or previous session is still timing out on server.	Append #### to your client name to generate a unique random ID (e.g., myclient_####), or wait 2 minutes for the server session to expire.
Cannot connect to server	Incorrect port or network firewall blocking the connection.	• For Java, Python, and ESP32: connect to port 4444 (TCP). • For WebSockets in browsers: connect to port 9000 at path /ws. • On institutional/school WiFi, ask network administrators if port 4444 is filtered.
Browser WebSocket fails on HTTPS	Mixed content security block.	Browsers block insecure ws:// connections from HTTPS pages. Use wss:// (secure WebSocket) when your web application is hosted on HTTPS.
Message sent, but receiver gets nothing	1. Channel spelling mismatch. 2. Missing subscription handler. 3. Testing sender and receiver on the same client.	1. Channel names are case-sensitive (Kitchen ≠ kitchen). 2. Verify that the receiving client subscribes with an event handler. 3. Self-Echo Prevention: By default, OOCSI does not echo messages back to the sending client. Use the built-in echo channel to test self-reception.
Device lag or high latency	Sending messages too frequently in an unthrottled loop.	Never send messages continuously in Processing’s draw() or ESP32’s loop() without a delay or timer. For state synchronization, use an OOCSI variable with built-in throttling.

---

Step-by-Step Diagnostic Flow

flowchart TD
    START(["Start: Prototype Issue"]) --> C1{"Can client connect<br/>to OOCSI server?"}

    C1 -->|No| S1{"Which client platform?"}
    S1 -->|Java / Python / ESP| S1A["Verify Port 4444 (TCP)<br/>Check local/campus firewall"]
    S1 -->|Browser / Web JS| S1B["Verify Port 9000 (/ws)<br/>If HTTPS host, use wss://"]
    S1A --> COLLISION{"Connection rejected?"}
    S1B --> COLLISION
    COLLISION -->|Yes| FIX_NAME["Append '####' to client name<br/>(avoid reconnect collision)"]
    COLLISION -->|No| FIX_SRV["Verify server is running<br/>(curl http://server:9000/metrics)"]

    C1 -->|Yes| C2{"Are messages received<br/>by destination?"}
    C2 -->|No| S2["Check Debugging Points:"]
    S2 --> S2A["1. Channel name case sensitivity ('Room' ≠ 'room')"]
    S2 --> S2B["2. Self-echo: OOCSI skips sender by default.<br/>Test with 'echo' channel!"]
    S2 --> S2C["3. Inspect /network or /dashboard to verify subscription"]

    C2 -->|Yes| C3{"Is latency high or<br/>hardware lagging?"}
    C3 -->|Yes| FIX_LAT["Throttle send loop!<br/>Avoid sending in draw() / loop() without delay.<br/>Use OOCSI variables with throttle."]
    C3 -->|No| SUCCESS(["System Healthy & Operational! 🎉"])

1. Verify Server Status:
   • If using a shared server (e.g., oocsi.id.tue.nl), visit its web landing page in your browser (http://<server>:9000/) or check /metrics.
   • If running locally, ensure the server container or JAR process is active.
2. Inspect with the Web Dashboard:
   • Open the server’s visual dashboard at /dashboard or the live network visualizer at /network.
   • Check whether your client handle appears in the connected clients list and whether your target channel has active subscribers.
3. Check the Log Console:
   • In Processing, check the console output.
   • On ESP/Arduino, open the Serial Monitor (115200 baud) to inspect connection logs and WiFi status.
   • In Python, check terminal output or enable logging.
   • In web browsers, open Developer Tools (F12) > Console to check for WebSocket connection errors.
4. Consult the FAQs:
   • Review common design and networking questions in our Frequently Asked Questions (FAQs).
5. Report an Issue:
   • If you suspect a platform bug, please submit an issue report on GitHub in the core OOCSI repository or reach out via our Contact page.