Barix RetailPlayer – Setup & Troubleshooting Guide

Applies to Firmware 7.0.4 and newer

1. Initial Setup Procedure

Verify Network Requirements
- Ensure firewalls allow traffic to the mandatory services listed in the Barix RetailPlayer Network Requirements guide: https://help.barix.com/knowledgebase/retailplayer-network-requirements
Register the Device in the target Portal.
Connect & Power Up
- Plug the Ethernet cable into the device.
- Power the unit on.
Wait for Auto‑Configuration
- The device will locate its portal URL (via the Flexa registry) and reboot.
- Allow ~5 minutes for this process.
Confirm Online Status – the device should appear in the portal as ONLINE once the LED turns solid green.

2. Common Failure Scenarios & Diagnostic Steps

What to do when the RetailPlayer doesn’t connect with the Portal.

2.1 LED Indications

LED State	Meaning	Recommended Action
Blinking Green	Application is running but no portal connection	Follow “No portal connection” steps below.
Even after 5 minutes from power up the LED remains solid red or blinking red	Major hardware fault	Open the unit. Verify the SD card is seated correctly. Try to eject and re-inser the SD Card and power up to verify if the issue is solved. If not proceed to next step. Replace the SD card with a brand‑new, unformatted card. Re‑connect network, power up, and wait 15 min. Power‑cycle again. If the fault persists, the unit may be RMA‑eligible – contact support@barix.com - reporting the failure and the MAC Address of the device.

2.2 Audio Announcement of IP Address

Does the device announces its IP Address during boot through the audio output? (feature known as “Sonic IP”)

Yes – Device obtained an IP via DHCP → LAN connectivity is OK. Continue to next step.
No – DHCP failure or network block. Verify:
1. LAN Blacklisting – Check MAC‑address filters on the switch where the player is connected.
2. DHCP Lease Table – Look for a Barix MAC beginning with 00:08:e1. Ensure the DHCP can allocate an IP Address to the RetailPlayer device.
3. VLAN Configuration – Ensure the port belongs to the correct VLAN.
4. Cable / Switch Port – Test with a known‑good cable and port.
5. Wi‑Fi Access Points (only applies to wifi networks) – RetailPlayer devices after fw v7.0.4, does not roam between APs. Disable AP‑side roaming (also known as DFA, but best to verify with the model in object) to avoid disconnections.

2.3 Device Has an IP but Still Won’t Connect to the Portal

Re‑confirm Network Requirements – firewalls must permit the services listed in the network‑requirements guide.
Static IP Checks – Ensure every entry (IP, subnet mask, gateway, DNS) is correct.
Allow Sufficient Boot Time
- After power‑up, wait ≥ 7 minutes.
- Firmware ≥ 7.0.4 checks the Flexa registry for the portal URL after ~5 minutes.
Log Retrieval & Analysis
- Access the device’s local web UI (enter its IP in a browser on the same LAN).
- Download the log bundle (see this video tutorial)
- Open retailplayer.log file with a text editor on your PC and perform the searches described below.

2.3.1 Portal URL Presence

Search for “Portal URL”. Most text editors allow to “find” text in a document very easily. Example of a correctly populated line:

CODE

2026/02/11 17:06:02.205772 ... main.cpp:213 (I) [main] UCI Portal URL: wss://myportal.com/be/api/v1/device/

Empty field (UCI Portal URL: with no value) → Device has not yet retrieved its portal URL from the Flexa registry. Wait up to 7 minutes and check again or continue with Flexa Registry connection diagnostics as instructed below.

2.3.2 Flexa Registry Diagnostic

Search for “Flexa”. Expected success line:

CODE

...portalUrlFetcher.cpp:   24 (I) [portal_url_fetcher]  Flexa Registry Portal URL: wss://myportal.com/be/api/v1/device/

Error example (SSL handshake failure):

CODE

2026/01/11 11:40:15.742662 ... portal_url_fetcher] Flexa Registry - 500 - SSL Exception: error:1416F086:SSL routines:tls_process_server_certificate:certificate verify failed

Possible Causes & Fixes

Symptom	Likely Cause	Remedy
SSL handshake fails	Device time is out‑of‑sync (see NTP troubleshooting below)	Verify NTP access is allowed through the firewall. Ensure the latest firmware (v8.0.0 at time of writing) is installed – newer releases improve NTP handling. Confirm DNS resolves the NTP servers.
DNS error for NTP	Incorrect DNS configuration	Update DNS settings or use a public resolver (e.g., 1.1.1.1 or 8.8.8.8).

Successful NTP sync logs look like (the following lines are only printed on firmware v8.0.0 onward):

CODE

2026/02/11 18:06:16.322664 ... NTPSyncCheck.cpp:46 (I) [ntp-check] NTP packet from 23.186.168.130
2026/02/11 18:06:16.323227 ... NTPSyncCheck.cpp:53 (I) [ntp-check] NTP in SYNC

2.3.3 WebSocket Connection

Search for “websocket”. Normal transition line:

CODE

... websocket] state changed from CONNECTING to CONNECTED

Then verify the portal heartbeat: search for “portal is ALIVE”. Example of a healthy connection:

CODE

... api] successful ANNOUNCE. apiKey='**********:04.350Z'
... api] portal is ALIVE --> STATIC LED.

Missing “ALIVE” line or error messages indicate a broken portal link;

3. Final Checklist Before Opening a Support Ticket

After power up you waited at least 7 minutes before confirming there is a problem
Network firewall permits all services listed in the RetailPlayer Network Requirements guide.
Device runs the latest firmware (v8.0.0 or newer).
DHCP or static IP configuration is verified (including DNS).
Network switches and cables are checked and known to work.
NTP synchronization succeeds (no DNS or time‑drift errors).
Flexa registry lookup returns a valid portal URL.
WebSocket connection state in the log file.

If all items are satisfied and the device still fails to stay online, contact Barix support with the following attachments:

Full log archive file (the entire .tar archive)
Screenshot of the device’s web UI (settings and status pages).
Description of the network topology (firewall/NAT rules, VLANs, Wi‑Fi AP model if applicable).