Help

IoT Troubleshooting Guide

Solutions for common IoT Digital Signage integration issues
Quick diagnostics, step-by-step fixes, and emergency recovery

[ SignService | GPIO | Events | Performance ]

Quick Navigation

Quick Diagnostic Commands
Connection Issues
SSL Certificate Errors
Callback Issues
GPIO Issues
DHT11 Sensor Issues
Event Issues
Performance Issues
Log Analysis
Emergency Recovery

► Watch Video Tutorial - Step-by-step guide to IoT Digital Signage setup

Quick Diagnostic Commands

Run these commands first to identify the source of your issue

Check Network Connectivity

# Test connection to SignService from Pi curl https://192.168.68.52:8094 --insecure -v # Check if port is open nc -zv 192.168.68.52 8094 # Check Pi IP address ip addr show | grep inet # Test callback reachability (from Windows) curl http://192.168.68.24:5001/health

Check Services

# Check if Node.js script is running ps aux | grep node # Check systemd service status systemctl status iot-relay # View recent logs journalctl -u iot-relay -n 50 # Check GPIO availability python3 -c "import lgpio; print('lgpio OK')"

Connection Issues

Problems connecting to SignService or network-related failures

Q: Cannot Connect to SignService

curl: (7) Failed to connect to 192.168.68.52 port 8094

Cause 1: SignService Not Running

The SignService daemon may not be running on the Windows host.

# On Windows:
Open Services (services.msc)
Find "SignService" or "SignageWatchDog"
If stopped, right-click -> Start
If not installed, reinstall SignService
                            

Cause 2: Windows Firewall Blocking

Port 8094 may be blocked by Windows Defender Firewall.

# Solution via Windows Firewall GUI:
1. Open Windows Defender Firewall
2. Click "Allow an app or feature through Windows Defender Firewall"
3. Add rule for port 8094 (both TCP and UDP)

# Or via Command Prompt (as Administrator):
netsh advfirewall firewall add rule name="SignService" dir=in action=allow protocol=TCP localport=8094
                            

Cause 3: Wrong IP Address

Your script may be using the wrong host IP.

# On Windows, find correct IP:
ipconfig

# Look for your local network adapter (not VirtualBox/VMware)
# Use the IPv4 Address shown
# Update SIGNSERVICE_HOST in your scripts
                            

Cause 4: Network Isolation

Devices may be on different networks or AP isolation is enabled.

# Verify connectivity:
Ensure Pi and Windows PC are on same network
Check router settings for AP isolation (disable it)
Test ping from Pi: ping 192.168.68.52
If on different subnets, configure routing
                            

Q: Getting SSL Certificate Errors

Error: self signed certificate in certificate chain

Solution for Node.js

Add the rejectUnauthorized option to bypass self-signed certificate validation:

// In Node.js, add to request options:
const options = {
    hostname: SIGNSERVICE_HOST,
    port: 8094,
    path: '/...',
    method: 'POST',
    rejectUnauthorized: false  // <-- Add this
};
                            

Solution for curl

Use the --insecure flag to skip certificate verification:

# Add --insecure flag:
curl https://192.168.68.52:8094/player/event --insecure
                            

Q: Callbacks Not Being Received

Registered for events but never receive callbacks

Diagnostic Steps

# 1. Verify registration
curl https://192.168.68.52:8094/player/registeredEvents --insecure

# 2. Check callback URL is correct (should show Pi's IP, not localhost)

# 3. Verify callback server is running
curl http://192.168.68.24:5001/health

# 4. Check Pi firewall (if enabled)
sudo ufw status
sudo ufw allow 5001/tcp  # Allow callback port
                            

Cause: Wrong Callback IP

The callback URL may be using localhost or an incorrect IP address.

# Problem: Callback URL uses localhost or wrong IP
# Solution: Verify getLocalIP() returns correct address

# Check what IP the script detects:
node -e "console.log(require('os').networkInterfaces())"
                            

Cause: Port Already in Use

# Check if port is in use
sudo lsof -i :5001

# Kill process using port
sudo kill -9 <PID>
                            

Cause: Callback Server Not Started

The script may exit before the HTTP server starts listening.

# Check with:
netstat -tlnp | grep 5001

# Ensure HTTP server is listening before script exits
                            

GPIO Issues

Hardware and relay control problems

Q: Relay Not Responding to Events

Events received but relay doesn't switch

Test GPIO Manually

# Test GPIO with Python script:
python3 << 'EOF'
import lgpio
h = lgpio.gpiochip_open(0)
lgpio.gpio_claim_output(h, 4)
lgpio.gpio_write(h, 4, 1)  # ON
print("Relay should be ON")
input("Press Enter to turn OFF")
lgpio.gpio_write(h, 4, 0)  # OFF
lgpio.gpiochip_close(h)
EOF
                            

Check lgpio Installation

# Verify lgpio is installed
python3 -c "import lgpio; print('OK')"

# Check GPIO permissions
ls -la /dev/gpiochip0
# Should show: crw-rw---- 1 root gpio ...

# Add user to gpio group
sudo usermod -aG gpio $USER
# Then logout and login
                            

Verify Wiring

RELAY WIRING VERIFICATION Check these connections: 1. Relay VCC -> Pi Pin 2 (5V) 2. Relay GND -> Pi Pin 6 (GND) 3. Relay IN -> Pi Pin 7 (GPIO 4) Test with multimeter: - VCC to GND should read ~5V - IN to GND should read ~0V when LOW, ~3.3V when HIGH

Q: DHT11 Sensor Not Reading

Temperature readings show null or error

Install Required Libraries

# Install Adafruit DHT library
pip3 install adafruit-circuitpython-dht
sudo apt-get install libgpiod2
                            

Test Sensor Directly

python3 << 'EOF'
import adafruit_dht
import board
dht = adafruit_dht.DHT11(board.D5)
try:
    print(f"Temp: {dht.temperature}C")
    print(f"Humidity: {dht.humidity}%")
except Exception as e:
    print(f"Error: {e}")
finally:
    dht.exit()
EOF
                            

Verify DHT11 Wiring

DHT11 WIRING DHT11 VCC -> Pi 3.3V (Pin 1) DHT11 DATA -> Pi GPIO 5 (Pin 29) with 10k pull-up resistor DHT11 GND -> Pi GND (Pin 6) Note: A 10k ohm pull-up resistor between DATA and VCC is recommended

Event Issues

Problems with events not updating displays or incorrect data format

Q: Events Sent But Display Not Updating

Script says "sent successfully" but SignPlayer shows nothing

1. Verify Event Name Matches (Case-Sensitive!)

# In SignStudio:
- Check the Data Binding configuration on your Label/Component
- Event Name must EXACTLY match what you're sending

# Script sends:
eventName=myCustomEvent

# SignStudio expects:
myCustomEvent

# Common mistake: "MyCustomEvent" vs "myCustomEvent"
                            

2. Verify Field Name Matches

// Script sends:
{ "name": "25.3" }

// SignStudio Data Binding should use:
{
  "eventName": "myCustomEvent",
  "field": "name"  // <-- Must match JSON key
}
                            

3. Check store Parameter

# Without store=1, events may not persist
curl '...?eventName=test&store=1' ...
                         ^^^^^^^
                         Add this for persistent events
                            

4. Verify Scene is Active

SignPlayer must be displaying the scene with the Data Binding
Check SignPlayer status - is it playing?
Try restarting SignPlayer

Q: Events Received in Wrong Format

Callback receives data but can't parse it correctly

Expected Callback Format

{
  "eventName": "clickAlarm",
  "timestamp": "2025-12-26T10:30:00.000Z",
  "data": {
    "clickAlarm": "on"
  }
}
                            

Correct Parsing Example

// In callback handler:
server.on('request', (req, res) => {
    let body = '';
    req.on('data', chunk => body += chunk);
    req.on('end', () => {
        const json = JSON.parse(body);

        // Access event name
        const eventName = json.eventName;

        // Access data payload
        const data = json.data;

        // Access specific field
        const alarmState = json.data.clickAlarm;

        console.log(`Event: ${eventName}, Alarm: ${alarmState}`);
    });
});
                            

Performance Issues

Latency, memory, and optimization solutions

Q: High Latency - Events Take Seconds to Appear

Events take several seconds to appear on display

1. Reduce Network Hops

Use wired Ethernet instead of WiFi
Ensure Pi and Windows PC are on same subnet
Check for network congestion

2. Optimize Polling Interval

// Don't poll too frequently
const POLL_INTERVAL = 4000;  // 4 seconds is reasonable

// For real-time needs, consider:
// - Event-driven GPIO interrupts
// - WebSocket connections
                            

3. Check CPU Usage

# On Pi - monitor CPU
top -p $(pgrep -f "node iot")

# If CPU is high:
# - Reduce logging
# - Optimize sensor reading
# - Use hardware interrupts
                            

Q: Memory Leaks - Script Crashes Over Time

Script uses more memory over time, eventually crashes

1. Close GPIO Handles After Use

function setRelay(on) {
    const cmd = `python3 -c "
import lgpio
h = lgpio.gpiochip_open(0)
lgpio.gpio_claim_output(h, 4)
lgpio.gpio_write(h, 4, ${on ? 1 : 0})
lgpio.gpiochip_close(h)  # <-- Always close!
"`;
    exec(cmd);
}
                            

2. Limit Stored Data

const eventLog = [];
const MAX_LOG_SIZE = 100;

function logEvent(event) {
    eventLog.push(event);
    if (eventLog.length > MAX_LOG_SIZE) {
        eventLog.shift();  // Remove oldest
    }
}
                            

3. Clear Intervals on Shutdown

const interval = setInterval(poll, 5000);
process.on('SIGINT', () => {
    clearInterval(interval);
    process.exit(0);
});
                            

Log Analysis

Enable verbose logging and analyze issues

Enable Verbose Logging

Add Debug Logging to Your Script

// Add to your script
const DEBUG = true;

function log(message) {
    if (DEBUG) {
        console.log(`[${new Date().toISOString()}] ${message}`);
    }
}

// Use throughout:
log('Sending event...');
log(`Response: ${response}`);
log(`Error: ${error.message}`);
                            

Log to File

# Run script with logging to file
node iotSendTemperture.js 2>&1 | tee /var/log/iot-temp.log

# Or configure in systemd service:
[Service]
StandardOutput=append:/var/log/iot-relay.log
StandardError=append:/var/log/iot-relay-error.log
                            

Analyze Log Files

# Find errors
grep -i error /var/log/iot-*.log

# Count events per hour
grep "sent successfully" /var/log/iot-temp.log | cut -d' ' -f1-2 | uniq -c

# Find connection issues
grep -E "(ECONNREFUSED|timeout|failed)" /var/log/iot-*.log
                            

Emergency Recovery

When all else fails, use these commands to reset everything

Reset Everything

# 1. Stop all IoT services
sudo systemctl stop iot-relay iot-temp

# 2. Kill any running Node.js processes
pkill -f "node iot"

# 3. Reset GPIO
python3 -c "
import lgpio
h = lgpio.gpiochip_open(0)
for pin in [4, 5, 6, 17, 18, 22, 27]:
    try:
        lgpio.gpio_free(h, pin)
    except:
        pass
lgpio.gpiochip_close(h)
print('GPIO reset complete')
"

# 4. Restart SignService on Windows (Run as Administrator)
net stop SignService
net start SignService

# 5. Restart IoT services
sudo systemctl start iot-relay iot-temp
                        

Factory Reset Pi IoT

# Re-sync files from development machine
rsync -avz --delete /c/msweb/pi root@10.0.0.24:/root/_node-dev/

# Fix line endings and permissions
ssh root@10.0.0.24 "find /root/_node-dev/pi -type f -not -path '*/node_modules/*' -exec dos2unix {} \; && chmod -R 777 /root/_node-dev/pi"
                        

Still Need Help?

If you've tried all troubleshooting steps and still have issues:

1. Gather Diagnostic Info

Script output/logs
Network configuration
GPIO wiring diagram
SignStudio scene config

2. Check Documentation

3. Contact Support

Include diagnostic info
Describe expected vs actual
Mention recent changes

Explore IoT Digital Signage

Learn more about our IoT integration capabilities:

live examples, see it in action

Checkout live examples of Digital Signage presentations. The SignPlayer can run everywhere, on Android, Windows, Mac, iPad and even inside your web browser

product pricing

Find out why people call us “the world’s most popular digital signage platform”

customers

Can it really be free?
What’s the catch?
Want to be amazed?
Read on...