Troubleshooting

Quick Diagnostic Checklist

Before detailed troubleshooting, verify these basics:

• Power LED illuminated (power connected and working)
• Network cable connected securely (Ethernet deployments)
• Gateway appears in Haltian IoT Studio (cloud connected)
• Firmware version is current (check for updates)
• No recent configuration changes (review change log)

Power Issues

Gateway Won’t Power On

Symptom: No LEDs illuminate when power is connected.

Possible Causes and Solutions:

1. No Power to Gateway

   • Check DC power supply is plugged in and working
   • Verify correct voltage (9-36V DC)
   • Test power supply with multimeter
   • Try different power outlet

2. Wrong Polarity (DC Jack)

   • Verify center pin is positive (+)
   • Check power supply matches specification
   • Replace power supply if polarity is reversed

3. PoE Issues (BLE Version)

   • Verify PoE switch supports 802.3af or 802.3at
   • Check Ethernet cable is Cat5e or better
   • Test PoE output with another device
   • Verify PoE budget on switch not exceeded

4. Hardware Failure

   • Check for visible damage to enclosure
   • Verify DC jack not damaged
   • Contact support for RMA if hardware fault suspected

Gateway Powers Off Unexpectedly

Symptom: Gateway powers on but shuts down during operation.

Possible Causes:

1. Insufficient Power Supply

   • Verify power supply rating (minimum 1A @ 12V)
   • Check for voltage drop under load
   • Upgrade to 2A power supply if borderline

2. Overheating

   • Verify ventilation clearance (10cm all sides)
   • Check ambient temperature <50°C
   • Remove any obstructions blocking airflow
   • Move away from heat sources

3. Intermittent Connection

   • Check DC jack connection (secure twist & lock)
   • Verify Ethernet cable for PoE (if used)
   • Inspect cables for damage

Power Consumption Higher Than Expected

Symptom: Power draw exceeds typical 3-5W operation.

Diagnostic Steps:

1. Check Active Interfaces

   • LTE uses more power than Ethernet/WiFi
   • Multiple active interfaces increase consumption
   • Disable unused interfaces

2. Monitor Sensor Load

   • High sensor count increases processing
   • High message rate increases power usage
   • Check for message storms (abnormal traffic)

3. Verify Normal Operation

   • Check CPU usage (<50% normal)
   • Review running processes
   • Reboot gateway to clear transient issues

Network Connectivity Issues

No Cloud Connection

Symptom: Gateway not appearing in Haltian IoT Studio.

Diagnostic Steps:

1. Verify Network Layer Connectivity

   # Via console access:
   ping 8.8.8.8           # Test internet connectivity
   ping cloud.haltian.com # Test Haltian cloud endpoint
   

2. Check DHCP/IP Assignment

   • Verify gateway has valid IP address
   • Check IP conflicts on network
   • Verify DHCP server is responding
   • Try static IP if DHCP problematic

3. Verify DNS Resolution

   nslookup cloud.haltian.com
   # Should resolve to Haltian cloud IP
   

4. Check Firewall Rules

   • Verify outbound HTTPS (port 443) allowed
   • Check NTP (port 123) accessible
   • Verify no deep packet inspection blocking TLS
   • Test from different network if possible

5. Verify Certificate Validity

   • Check system time is correct (NTP sync)
   • Verify gateway certificate not expired
   • Check certificate chain is valid

Solutions:

• Static IP: Configure if DHCP unavailable
• Firewall: Whitelist gateway MAC/IP address
• NTP: Configure alternate NTP server if blocked
• Certificate: Update firmware if certificate issues

Intermittent Cloud Connection

Symptom: Gateway connects but drops connection periodically.

Possible Causes:

1. Network Instability

   • Check for packet loss
   • Monitor network congestion
   • Verify switch/router stability
   • Test with different network port

2. WiFi Signal Issues (WiFi Deployments)

   • Check RSSI strength (>-70 dBm recommended)
   • Monitor channel interference
   • Move closer to access point
   • Switch to less congested channel or 5 GHz band

3. LTE Signal Issues (LTE Deployments)

   • Check RSRP (>-90 dBm recommended)
   • Monitor SINR (>10 dB recommended)
   • Reposition antenna for better signal
   • Verify carrier coverage in area

4. Overloaded Gateway

   • Check CPU usage (<70%)
   • Monitor message queue depth
   • Reduce sensor count if over capacity
   • Upgrade firmware if memory leak suspected

Slow Cloud Communication

Symptom: High latency in data uploads or configuration changes.

Diagnostic Steps:

1. Measure Latency

   # Via Studio diagnostics:
   - Cloud ping: Should be <200ms
   - Message upload time: <2 seconds typical
   

2. Check Bandwidth

   • Verify minimum 1 Mbps available
   • Monitor bandwidth usage on network
   • Check for competing traffic (streaming, downloads)
   • Implement QoS if needed

3. Check Backhaul Type

   • Ethernet: Best performance
   • WiFi 5 GHz: Good performance
   • WiFi 2.4 GHz: Moderate performance
   • LTE: Variable (carrier dependent)

Solutions:

• Switch to Ethernet for best performance
• Use WiFi 5 GHz band instead of 2.4 GHz
• Upgrade LTE plan for higher priority
• Reduce message rate to match bandwidth

Wirepas Mesh Issues

Sensors Not Connecting

Symptom: Sensors not joining mesh network.

Diagnostic Steps:

1. Verify Gateway Mesh Status

   • Check BLE radio is active
   • Verify Wirepas service running
   • Confirm network channel configured (0-39)
   • Check sink role enabled

2. Check Sensor Proximity

   • Verify sensors within range (5-25m typical indoor)
   • Remove obstacles (concrete walls, metal barriers)
   • Test with sensor closer to gateway
   • Check for RF interference

3. Verify Network Configuration

   • Confirm network address matches sensors
   • Check channel configuration (same as sensors)
   • Verify no conflicting networks nearby
   • Review sensor configuration (matches gateway)

Solutions:

• Move sensors closer to gateway
• Add intermediate sensors to extend range
• Change network channel to avoid interference
• Verify sensor firmware compatible with gateway

Poor Mesh Performance

Symptom: High latency, low message delivery rate.

Diagnostic Steps:

1. Check Network Metrics

   • Message delivery rate: Should be >98%
   • Average latency: Should be <2 seconds
   • Hop count: Should be <8 hops typical
   • Route stability: <10 changes/hour

2. Analyze Network Topology

   • Check hop count distribution
   • Identify single points of failure
   • Verify redundant paths exist
   • Look for bottleneck nodes

3. Monitor Interference

   • Scan for WiFi networks on same channel
   • Check for Bluetooth devices
   • Identify other 2.4 GHz sources (microwaves, etc.)
   • Test on different Wirepas channel

Solutions:

• Add more sensors to create redundant paths
• Reposition sensors for better connectivity
• Change Wirepas channel (10-20 recommended)
• Adjust sensor placement to reduce hops

High Message Loss

Symptom: Messages not reaching cloud (delivery rate <95%).

Possible Causes:

1. Network Congestion

   • Too many sensors per gateway (>200)
   • Message rate too high (>5000/hour)
   • Queue overflow at gateway
   • Insufficient bandwidth to cloud

2. RF Interference

   • Competing 2.4 GHz devices
   • Metal barriers blocking signals
   • Long range forcing weak signals
   • Channel interference

3. Gateway Overload

   • CPU usage >80%
   • Memory exhaustion
   • Storage full
   • Too many concurrent sensors

Solutions:

• Reduce sensor count per gateway
• Decrease sensor report intervals
• Add additional gateways for load balancing
• Change Wirepas channel
• Upgrade firmware if performance regression

Configuration Issues

Cannot Apply Configuration

Symptom: Configuration changes not taking effect.

Diagnostic Steps:

1. Verify Configuration Syntax

   • Check JSON format is valid
   • Verify all required fields present
   • Check value ranges are correct
   • Test with known-good configuration

2. Check Permission

   • Verify user has admin role
   • Check gateway is not locked
   • Confirm account has proper access

3. Review Gateway Status

   • Gateway must be online
   • Verify no firmware update in progress
   • Check gateway not in error state

Solutions:

• Validate JSON before applying
• Wait for gateway to come online
• Complete firmware update before reconfiguring
• Contact support if permissions issue

Configuration Resets Unexpectedly

Symptom: Configuration reverts to default or previous state.

Possible Causes:

1. Firmware Rollback

   • Failed firmware update
   • Automatic rollback to previous version
   • Configuration incompatible with firmware

2. Cloud Sync Issue

   • Configuration not saved to cloud
   • Sync conflict (multiple users editing)
   • Network interruption during save

3. Hardware Issue

   • Failed eMMC storage
   • Power loss during write
   • Corrupted configuration file

Solutions:

• Re-apply configuration after firmware stable
• Ensure configuration saved successfully
• Verify no conflicting changes from other users
• Contact support if persistent

Firmware Update Issues

Update Fails

Symptom: Firmware update does not complete successfully.

Diagnostic Steps:

1. Check Download

   • Verify internet connectivity during download
   • Check available storage (>500MB free)
   • Monitor download progress
   • Verify checksum after download

2. Check Installation

   • Ensure no power interruption during update
   • Verify sufficient battery backup (supercap charged)
   • Check no configuration changes during update
   • Review update logs for errors

Solutions:

• Retry update with stable internet connection
• Clear storage space if low
• Ensure stable power during update
• Contact support if repeated failures

Gateway Unresponsive After Update

Symptom: Gateway does not respond after firmware update.

Steps:

1. Wait for Automatic Rollback

   • Gateway may auto-rollback (wait 5-10 minutes)
   • Monitor LED status for recovery indication
   • Check if gateway reconnects to cloud

2. Manual Power Cycle

   • Disconnect power for 30 seconds
   • Reconnect power and wait for boot (60 seconds)
   • Check if gateway recovers to previous firmware

3. Factory Reset

   • Access reset button (internal, requires opening)
   • Hold reset during power-on (10 seconds)
   • Gateway restores to factory firmware
   • Reconfigure network and cloud connection

Performance Issues

High CPU Usage

Symptom: CPU usage consistently >70%.

Diagnostic Steps:

1. Check Running Processes

   • Identify processes consuming CPU
   • Look for runaway processes
   • Check for memory leaks

2. Review Workload

   • Count active sensors
   • Calculate message rate
   • Check for message storms

Solutions:

• Reduce sensor count to <200
• Decrease message reporting frequency
• Reboot gateway to clear transient issues
• Update firmware if known CPU bug

High Memory Usage

Symptom: Memory usage >80%, potential out-of-memory errors.

Possible Causes:

• Memory leak in firmware
• Message queue overflow
• Too many concurrent connections
• Logging misconfiguration

Solutions:

• Reboot gateway to free memory
• Reduce message queue size
• Disable verbose logging
• Update firmware if known memory leak

Storage Full

Symptom: Storage usage >90%, logs being dropped.

Diagnostic Steps:

1. Check Storage Usage

   # Via console:
   df -h
   # Check eMMC usage
   

2. Identify Large Files

   • Check log file sizes
   • Look for core dumps
   • Review old firmware images

Solutions:

• Clear old log files
• Delete old firmware images
• Reduce log retention period
• Use remote logging (cloud/syslog)

Monitoring

How to Access Logs

Via Haltian IoT Studio:

1. Navigate to gateway settings
2. Select “Diagnostics” → “Logs”
3. Choose time range and log level
4. Export logs if needed

Via Console Access:

# View system logs
journalctl -u wirepas-gateway
journalctl -u network-manager

# View real-time logs
tail -f /var/log/messages

Key Metrics to Monitor

Getting Help

Diagnostic Report

Generate diagnostic report to send to support:

1. Access Haltian IoT Studio

2. Navigate to Gateway → Diagnostics

3. Generate Report - Includes:

   • System logs
   • Configuration
   • Network status
   • Performance metrics
   • Recent errors

4. Download Report (ZIP file)

5. Send to Support with description of issue

Contact Support

Email: support@haltian.com

Include in Support Request:

• Gateway UUID
• Firmware version
• Diagnostic report (if available)
• Description of issue
• Steps to reproduce
• When issue started
• Recent changes (if any)

Emergency Recovery

For critical failures:

1. Power Cycle Gateway

   • Disconnect power 30 seconds
   • Reconnect and wait for boot

2. Network Reset

   • Disconnect all network cables
   • Wait 30 seconds
   • Reconnect one interface at a time

3. Factory Reset (last resort)

   • Opens enclosure (breaks seal)
   • Press reset button during power-on
   • Reconfigure from scratch

Common Error Codes

Next Steps

• Configuration - Review configuration settings
• Operation - Understand normal operation
• Specifications - Check technical limits
• Contact Support - Get assistance from Haltian team