Using Zello Bridge With Radio Gateways

This article is written for: ✅ Zello Work ❌ Zello Friends & Family.

Bridge connects traditional two-way radios with Zello’s powerful push-to-talk (PTT) solution, enabling seamless cross-platform communication so teams can use both the hardware and software that’s optimized for their unique operational environment.

Bridge runs quietly in the background, ensuring non-disruptive interoperability between radio users and Zello. Its latest release expands capability to include both USB and JPS gateways, as well as provides an updated management UI for more friendly and accessible usage.

Networks that have historically utilized Zello’s legacy PC app will find Bridge a vital tool in their communications ecosystem. Zello plans to sunset the legacy PC app in the near future, so we highly recommend migrating to Bridge as soon as possible to ensure you’re receiving the best support and most updated product.

Compatibility

This application is compatible with USB and JPS gateways. While both gateway types connect radios with communications software, they differ in how they transmit audio; USB gateways require direct USB connection to a PC, whereas JPS gateways generally transmit messages using Radio Over IP (RoIP) technology, meaning audio is delivered via an internet connection.

Common models of these gateways include:

USB

JPS

Please note that while above-listed JPS gateways require utilization of Zello Bridge, newer JPS gateway models include updated firmware that enables connection via the JPS management interface.

For example, JPS gateways like the ACU-Z1 and RSP-Z2 already have the Zello Chanel API integrated. While they’re compatible with Bridge, they don’t require it. See this JPS documentation for more information.

Bridge is only compatible with channel communications. Because it relies on Zello’s channel API, it can’t be used for 1:1 messages. It’s currently exclusively available in a x64 bit package.

How it Works

Bridge expands Zello’s functionality beyond traditional Android and iOS operating systems, allowing devices operating on proprietary firmware to integrate with the Zello infrastructure.

When configured with either a JPS or USB gateway, Bridge connects two-way radios with Zello, enabling smoother, more tailored PTT communications. It reads a 2-level structure from the configuration file: links and connectors.

Links share the audio streams between connectors. They’re what ensure communications are transmitted from one connector to the other (i.e. from Zello to your team’s radios).

While links are dependent on their designated connectors, they don’t interact with other links. Each link will have at least two connectors—the Zello API, the JPS gateway, or the USB gateway —and additional, platform-specific configuration attributes that dictate Bridge’s configuration.

Bridge easily supports up to 16 links.
Connectors are the endpoints you’re connecting using Bridge—for example, Zello’s channel API and a USB gateway. There are three possible endpoints: the Zello channel API, a USB gateway, or a JPS gateway. Each link includes at least two connectors; connectors are required attributes of a link's configuration.

Status Page

One of Bridge’s strengths lies in your ability to monitor its status through a webpage, providing access to real-time updates on your system’s performance. Once you’ve configured your links, their status will be displayed on the dashboard, offering targeted insight into the operations of each of your links and their associated connectors.

The status page is configured under the REST server section of the configuration file. It's accessible through port :8810.

Setup

In this article, we'll walk through configuring your instance of Zello Bridge. Additionally, we'll provide context for errors you may receive when using Bridge. If you have questions at any point in this process, please don't hesitate to contact our team at [email protected].

Please note: Zello communicates on multiple domains and subdomains—including zellowork.io. If you experience connectivity issues, consider allowing access by domain name. Please contact our team for a full list of available domains/subdomains.

Step 1: Install Bridge

Click this link to download Bridge's installation package (version 1.28.1).
Run the installation package on your computer. Once installed, Bridge will automatically launch.
Open your browser of choice and type 127.0.0.1:8810 in the address bar. This will take you to Bridge's status page, which indicates a successful installation.

Step 2: Configure the Zello Connector

Use the convenient user interface to easily and quickly configure Bridge

The first setup form establishes the link and the first connector that connects to your gateway user.

click create link
Fill in the empty fields with the relevant information

Parameter	What is it?	Example Value
Link name	The name of link	Link #1
Connector Name	The connector’s name	Zello connector
Channel	The name of your channel you’d like to connect to the gateway. Please note that the channel must be pre-existing by this step. For information on creating channels, see this article.	Radio Channel
Username	Username of an existing user profile. See this page for assistance creating a new user. This username should be created specifically for the link you’re setting up. Please note that the username cannot be in use on another device or in another Zello Bridge link. It should be created for a single, specific link. Ensure this user has been added to the channel you’ve assigned in the attribute above.	Gateway User
Password	The password associated with the username provided above.	mypassword1234!
Network Name	Your ZelloWork Network name	mynetwork

Step 3: Configure the gateway connector

The second setup form configures the gateway connector

Create a link

Parameter	What is it?	Example Value
Connector Name	The connector’s name	gateway connector
Gateway Type	The type of gateway	USB Gateway or JPS Gateway
Playback Device	The selected speaker that will play the transmissions being received over the network. This is auto-populate from your computer's sound settings.	Speakers (2 - USB device)
Recording Device	The selected microphone that will record transmissions being sent over the network. This is auto-populate from your computer's sound settings.	Microphone (2-USB device)
TX Mode	Transmission Mode	If you're using VOX on Zello Bridge, select VOX Activated. If you're using a USB gateway, select USB Serial Port
* Serial Port (If using USB Serial Port)	The operating system-assigned name of the connected gateway’s serial port. The serial port name can be found in your Device Manager. utilizes the serial port line state to start and stop TX message transmission (to radio).	COM3
*Serial Port Line (If using UBS Serial Port)	RTS is the most common value This field is dependent on the gateway in use. Please refer to your gateway’s manual for more information.	RTS or DTS
Activate Level	This field is dependent on the gateway in use. Refer to your gateway’s manual for more information. [what does this parameter do?]	high or low
RX Mode	Receiving Mode	If you're using VOX or a USB serial port on Zello Bridge, select VOX activated. [when to select USB Serial port?]
Serial Port Line	The operating system-assigned name of the connected gateway’s serial port. The serial port name can be found in your Device Manager. utilizes the serial port line state to start and stop RX message transmission (From radio)	Leave blank if using VOX activation
Active level	what does this do?	high or low

VOX Settings

Parameter	What is it?	Example Value
Activation (dB)	The sound level at which Bridge will activate transmission. The accepted values range from -80db (lowest) to 0db (highest).	-35
Deactivation (dB)	The sound level at which transmission is deactivated. This cannot be set higher than the activation threshold, and it’s best to set it between 3 and 5db lower.	-37
Trigger (ms)	The amount of time (in milliseconds) VOX takes to start transmission. Increasing the trigger time will help eliminate false transmissions caused by short impulses.	200
Relaxation (ms)	The amount of time (in milliseconds) the gateway waits between transmission of two messages. This setting helps prevent overlapping messages. Only applicable to VOX messages.	700
Pause time (ms)	The length in milliseconds of a loud, single-tone signal Bridge inserts before every VOX message. This ensures the radio recognizes the new transmission. Best set to 0	0

*Please note that JPS gateways require additional setup in the JPS management interface. See the Additional Information for JPS Gateways section below

Additional Information for JPS Gateways

Once you've created your Bridge configuration file, you'll also want to add a connection profile matching JPS RoIP connector configurations in your JPS radio gateway management interface. For detailed instructions about configuring JPS radio gateway hardware, please refer to your JPS product documentation.

Configuration Demo Video

Coming soon.

Troubleshooting

You may encounter a variety of errors when setting up your Bridge environment. The table below lists the possible error codes and their meanings. If you run into trouble resolving these errors, don’t hesitate to contact our team for tailored assistance.

Error Codes

Code	Meaning	How to solve it?
1001	Connector is not ready to process the incoming audio	Make sure incoming audio is not split into series of ultra short messages
1002	Linked connector has failed to process the audio	The problem is related with another (linked) connector
1003	Still sending previous message	Make sure incoming audio is not split into series of ultra short messages
1004	Receiving another message	Check if full-duplex mode is supported for all connectors in the link. If not (ie Zello channel does not support sending and receiving at the same time) – turn off full-duplex mode
1005	Unable to send outgoing audio	It could be network connectivity problem, or jitter buffer too small (Bridge has nothing to send)
2001	Failed to resolve JPS gateway address	Check remote_ip and remote_port configuration values
2002	Failed to resolve host address	Check local_ip and local_port configuration values
2003	Gateway connect failed	Check gateway endpoint is accessible from the Bridge host / specified local endpoint
2004	JPS Gateway offline	Connectivity issue or JPS hardware problem
2005	Read bad packet	MITM or proxy corrupts payload or anyone other connectivity issue
2006	Read bad audio packet	Could be unsupported codec or payload corruption
2007	Received bad audio packet	Other connector transmits unsupported audio format
2008	Read audio timeout	JPS Gateway does not send audio packets with expected speed, check JPS device settings
2009	Read buffer starving	JPS stopped sending audio packets for a while, larger jitter_buffer_size config value may resolve the problem
2010	Send buffer starving	Other connector stopped sending audio packets for a while, larger jitter_buffer_size config value may resolve the problem
2011	Send keepalive failed	Problem with sending message(s) to JPS Gateway
2012	Send timeout	Other connector unexpectedly stopped transmitting audio for a long time, outgoing message to JPS will be finished gracefully
3001	Not connected	Unable to initiate connection to Zello network, “channel_api_url” could be invalid Also this code registered if other connector tries to send audio to the not connected Zello connector
3002	Invalid Zello credentials	Make sure that the username, password and network in Zello connector configuration in zellobridge.json file are entered correctly, save the changes, and restart Zello Bridge Could be the connectivity problem either
3003	Channel offline	Connectivity problem or someone disconnected Bridge zello user from the configured zello channel. Not an issue if channel reconnect happened within seconds
3004	Opus encoder failed	Bridge failed to create opus packet, might be a problem with audio received from the other connector
3005	Opus decoder failed	Invalid opus packet received from Zello connection: MITM or proxy corrupts data, or anyone other connectivity issue
3006	Start stream failed	Unable to start outgoing message; if this happens often, Bridge zello account might be granted extra channel priority
3007	Stop stream failed	Most likely current message already interrupted by any other zello channel user, not an issue in this case
3008	Error received	Bridge received some error from channel api, should be some additional context
3009	Kicked	Some other Zello client device signed in with credentials used by this Bridge connector
3010	need a pause before starting a new stream	Set pause time (ms) to 0 Set stream guard timeout (ms) to 0
4001	Audio device not connected	Connect USB audio device or check audio device names in the OS
4002	Serial port not connected	Connect usb/serial device or check existing serial ports in the OS
4003	Audio device failed	Check audio device driver update
4004	Serial port failed	Reconnect / restart the device that provides serial port
4005	Port audio library failure	Check audio device driver update
4006	Audio recording overflow	Some recorded audio samples have been dropped, check host device performance / audio device driver update, could be deadlocks in the Bridge src
4007	Audio recording underflow	Some samples have not been recorded, a chunk of silence provided to the Bridge. Check audio device driver update, could be deadlocks in the Bridge src
4008	Recording buffer full	Identical to 4006, deadlock/bottleneck during the post-processing of the recorded audio by bridge itself. Host device performance may also trigger this error, though it is highly unlikely
4009	Resampling failure	Check logs for possible clues

Send a Log to the Zello Team

Logs provide additional context for the error codes you’re receiving. If you find yourself unable to resolve an issue, submit a log through the Bridge interface, then email us at [email protected] for assistance.

To send a log from Zello Bridge:

1. From the Bridge interface, click Send log. Enter your email and describe the issue you’re experiencing. Then click Send to Zello.
Email [email protected]. Let our team know you’ve recently submitted a log, and provide any additional context you think will aid the troubleshooting process.

Please note that we don’t monitor log submission, so it’s important that you email our team notifying us that you’ve sent a log. Additionally, it’s important that you send a log quickly after you’ve encountered an issue.

Using VOX on Zello Bridge

Zello Bridge also supports sharing audio without a gateway device using VOX.

With a traditional two way radio, you can share audio from your radios into Zello one way.
With a VOX enabled radio, you can share audio to and from Zello two ways.

Requirements for using VOX with your radios:

A USB soundcard
Cables that connect from your radio’s microphone and speaker jacks to your sound card, functioning as a microphone and speaker input/output

Configuration

You will need to set your TX Mode and RX Mode in step 3 to VOX Mode

When using external hardware like a USB soundcard, the playback device and recording device values in your setup form should reference the USB soundcard.

Please note: You do not need Radios to use VOX on Bridge. However, you must ensure that the playback device and recoding device values match the audio source you intend to use, as configured in your Windows sound settings.