• Turn on the radio
• Press the green button to go into the menu

• Go to General Settings

• Open up Digital Mode

• Check Enable, set your Share location interval to your desired time and make sure format is BSS
• Set Digital Channel to the channel you want to broadcast the signal over

 

 

BTECH ATAK Relay Plugin - User Guide

Version: (Refers to Plugin Version, e.g., 2.2.0 - Check CHANGELOG.md for specific version)

1. Introduction

The BTECH ATAK Relay Plugin serves as a bridge, connecting the BTECH (Baofeng Tech) smartphone application with the Android Team Awareness Kit (ATAK). This integration enhances situational awareness and communication capabilities for ATAK users by leveraging BTECH/Baofeng handheld radios.

Key Capabilities

• View Radio Locations: See BTECH radios as virtual contacts on the ATAK map.
• Two-Way Text Messaging: Send text messages from ATAK to the BTECH app for radio transmission and receive messages from radios into ATAK. (Requires Android Accessibility Service for sending).
• Push-To-Talk (PTT): Initiate voice transmissions using a button on the interface.
• Receive Radio Data: Display specially formatted Cursor-on-Target (CoT) messages and route data from radios connected to the BTECH app.
• Network Discovery: Discover and display BTECH radios relayed by other plugin users on the network across a TAK Server or MANET.

2. Requirements

To use the BTECH ATAK Relay Plugin effectively, ensure you have the following:

• ATAK: A compatible version of ATAK (e.g., SDK 5.3.0.12 environment as mentioned in development notes).
• BTECH Smartphone Application: The com.benshikj.ht.btech application must be installed and operational on the same Android device.
• BTECH Relay Accessibility Service: This service must be enabled in Android Settings for features like sending messages from ATAK to the BTECH app via the “MSG” button or Radial Menu.
• Android Permissions: Grant any permissions requested by the plugin upon installation or first use.

3. Installation and Setup

Follow these steps to install and configure the plugin:

3.1. Install the Plugin

Install the BTECH Relay plugin APK file onto your ATAK device.  After you install the apk, if the plugin does not show up tap the blue arrows up top

3.2. Configure BTECH App

Ensure the BTECH smartphone application is installed, configured, and functioning correctly on your device. This is essential for local radio discovery (RF mode).

You must change the voice messaging to text and leave the app running in the background

3.3. Enable Accessibility Service

The Accessibility Service is critical for sending messages from ATAK to the BTECH app.

1. Open the BTECH Relay plugin within ATAK (usually found in the plugin dropdown or toolbar).
2. Tap the Settings icon (often a gear symbol).
3. Tap the button labeled “Setup BTECH Relay Service” (or a similar name). This will take you to Android’s Accessibility settings.
4. In the list of downloaded services or apps, find “BTECH Relay Service” and enable it.
5. Grant any permissions requested by the service.

• Without this service, the “MSG” button and sending data via the Radial Menu will not work.

3.4. Grant Plugin Permissions

When you first run the plugin, or upon installation, Android may ask you to grant certain permissions. Ensure these are granted for full functionality.

4. Plugin Interface Overview

4.1. Main View

This is the primary interface for the BTECH Relay plugin.

• Plugin Title & Main Relay Toggle:

• The plugin’s name is displayed at the top.
• A prominent toggle switch (usually top right) enables or disables the core functionality of the plugin. This switch controls polling the local BTECH app for radio information and messages. Turn this ON to discover local radios and process messages from them.

• Settings Button (Gear Icon):

• Opens the plugin-specific settings popup/pane where you can configure various options.

• Connected Radios List:

• Displays radios discovered by the plugin. Each entry typically shows:

• Callsign: The identifier of the radio.
• Status:
• ACTIVE (RF): Radio discovered locally via the BTECH app and has a GPS fix.
• ACTIVE (NET): Radio discovered via another BTECH Relay plugin on the network.
• NO GPS (RF): Radio discovered locally but currently has no valid location.
• Disconnected: Radio was previously active but is now considered stale (hasn’t been seen for a configurable period).
• Last Seen: Time since the radio’s last update.
• Distance: Distance from your ATAK device to the radio.
• Frequency: The frequency the radio is reportedly using (if available).
• Color Indicator Dot: A colored dot visually representing the radio. For RF-discovered radios, tapping this dot allows you to change its color on your local map.

• Message Input Area:

• Text Field: Enter text messages you want to send via the connected BTECH radio.
• “MSG” Button: Sends the text from the input field to the BTECH app for transmission. Requires the Accessibility Service to be active.
• “PTT” Button: Initiates a Push-To-Talk voice transmission. This sends intents compatible with the Zello application.

• Footer:

• Displays plugin version/build information and the current relay status (e.g., “Relay Active,” “Relay Inactive”).

4.2. Map Widget

A small icon, typically located in the bottom-right corner of the ATAK map, indicates the status of the main relay (local BTECH DB polling): * Blue Icon: Main relay is active. * Gray Icon: Main relay is inactive.

4.3. Settings Popup/Pane

Accessible via the gear icon in the main plugin view. Here you can customize the plugin’s behavior. All Switch controls use distinct blue (ON) and gray (OFF) styling for clear visual feedback.

• CoT Broadcast Enabled: (Switch, default: ON)

• When ON, the plugin broadcasts CoT markers for locally discovered BTECH radios to other ATAK users on the network.

• Rebroadcast Radio Chat: (Switch, default: ON)

• When ON, plain text messages received from radios (via the BTECH app) are rebroadcast as new network CoT chat messages to other ATAK users.

• Network Radio Discovery: (Switch, default: OFF)

• When ON, the plugin listens for and displays BTECH radios being relayed by other BTECH Relay plugin instances on the network.

• Radial Menu Enabled: (Switch, default: ON)

• When ON, allows sending data from compatible ATAK map items (like points or routes) to the BTECH app via the Radial Menu. Requires the Accessibility Service.

• Stale Timeout: (Input, minutes, default: 5)

• Defines how long a radio can be unheard from before it’s considered “Disconnected” and its CoT marker is removed from the map.

• Polling Interval: (Input, seconds, default: 3)

• How frequently the plugin checks the BTECH app’s database for new information.

• Accessibility Service Buttons:

• “Setup BTECH Relay Service” (or similar): Opens Android Accessibility settings to enable/disable the service.
• “Check Service Status” (or similar): Verifies if the Accessibility Service is currently active.

5. Core Features and Usage

5.1. Relaying BTECH Radio Data (RF Discovery)

When the main relay toggle is ON, the plugin polls the BTECH app’s local database for information about connected radios.

• Virtual Contacts: For each discovered radio, the plugin creates a virtual Cursor-on-Target (CoT) marker (a-f-G-U-C) on the ATAK map.

• The radio’s callsign is used as its unique ID.
• If location data is available, the marker is placed at that location. Otherwise, it defaults to (0,0) indicating presence only.
• These markers are typically color-coded (default Cyan, user-configurable for RF radios via the radio list).
• They do not have an <archive /> tag, meaning they will expire based on their stale time.

5.2. Network Radio Discovery (NET Discovery)

If “Network Radio Discovery” is enabled in settings, the plugin listens for CoT events broadcast by other BTECH Relay plugins on the network.

• These network-discovered radios appear in the “Connected Radios” list, typically marked with (NET).
• Their color on the map is automatically inherited from the group name attribute of the incoming CoT event. You cannot change the color of NET-discovered radios locally.

5.3. Sending Messages from ATAK to Radio

1. Ensure the BTECH Relay Accessibility Service is enabled (see Section 3.3).
2. In the plugin’s main view, type your message into the text input field.
3. Tap the “MSG” button.
4. The plugin will use the Accessibility Service to input and send this message through the BTECH app.

5.4. Initiating PTT Voice Transmissions

1. Ensure the Zello application (or another PTT app compatible with Zello intents) is installed and configured.
2. In the plugin’s main view, tap the “PTT” button.
3. This sends com.zello.ptt.down (when pressed) and com.zello.ptt.up (when released, simulated by the plugin) Android broadcast Intents.

5.5. Receiving Messages and Data from Radios

The plugin processes different types of messages received from radios via the BTECH app:

• CoT Messages:

• Text messages from the BTECH app database prefixed with \"cot,\" (e.g., cot,a-f-G-U-C,UID,CALLSIGN,LAT,LON,ALT,REMARKS).
• These are parsed and displayed as standard CoT events/markers within ATAK.
• If “CoT Broadcast Enabled” is ON, these can be re-broadcast to the network.

• Route Messages:

• Multi-line text messages starting with \"ROUTE_DATA,\" followed by \"WAYPOINT_DATA,\" lines.
• These are reconstructed and displayed as ATAK Route map items.

• Plain Text Chat:

• Messages from the BTECH app that are not CoT or Route data are forwarded to the local ATAK GeoChat.
• If “Rebroadcast Radio Chat” is enabled, these messages are sent as new network CoT chat events (b-t-f).

5.6. Using the Radial Menu

If “Radial Menu Enabled” is ON in settings, and the Accessibility Service is active:

1. Select a compatible map item in ATAK (e.g., a point marker, a route).
2. Open the Radial Menu for that item.
3. You should find an option to send the item’s data (formatted as a “cot,…” string or multi-line route CSV) to the BTECH app for transmission.

5.7. Broadcasting and Re-broadcasting Data

The plugin manages the flow of information to the wider ATAK network:

• CoT Broadcast (for local RF radios): Controlled by “CoT Broadcast Enabled.” When ON, virtual contacts generated for your locally connected BTECH radios are sent to the network.
• Rebroadcast Radio Chat: Controlled by “Rebroadcast Radio Chat.” When ON, plain text messages received from radios are relayed to the network as CoT chat messages.
• Rebroadcasting Parsed CoT from Radios: If “CoT Broadcast Enabled” is ON, CoT messages (like cot,a-f-G-U-C...) received from radios are also re-broadcast to the network.

6. Configuration Options (Settings Explained)

This section details the settings available in the plugin’s settings pane (accessed via the gear icon).

• Main Relay Toggle (in Main View):

• Function: Enables/disables the primary function of polling the local BTECH app database.
• Impact: When OFF, no local radio data is processed, no RF discovery occurs, and no messages from local radios are handled.

• CoT Broadcast Enabled: (Switch)

• Default: ON
• Function: Controls whether CoT markers for BTECH radios discovered locally (RF Discovery) and parsed CoT messages received from radios are broadcast to the ATAK network.
• Usage: Keep ON to share your radio locations and received CoT data with your team. Turn OFF if you only want to see local radio data on your device.

• Rebroadcast Radio Chat: (Switch)

• Default: ON
• Function: If enabled, plain text messages received from radios (and displayed in your GeoChat) will be rebroadcast as new CoT chat messages to the ATAK network.
• Usage: Keep ON to share radio text communications with the team. Turn OFF to keep radio chats local to your device.

• Network Radio Discovery: (Switch)

• Default: OFF
• Function: When ON, your plugin will listen for and display CoT markers of BTECH radios being broadcast by other BTECH Relay plugin users on the network.
• Usage: Turn ON to see radios connected to teammates’ BTECH Relay plugins.

• Radial Menu Enabled: (Switch)

• Default: ON
• Function: Enables the feature to send ATAK map item data (points, routes) to the BTECH app via the item’s radial menu.
• Requirement: The BTECH Relay Accessibility Service must be active for this to function.
• Usage: Keep ON for quick sharing of locations or routes over radio.

• Stale Timeout: (Numeric Input)

• Units: Minutes
• Default: 5 minutes
• Function: Sets the duration after which a radio is considered “Disconnected” if no new updates are received. Disconnected radios are eventually removed from the map and lists.
• Usage: Adjust based on expected communication intervals. Shorter times mean faster removal of potentially offline radios; longer times mean radios persist on the map longer despite no updates.

• Polling Interval: (Numeric Input)

• Units: Seconds
• Default: 3 seconds
• Function: Determines how often the plugin checks the BTECH app’s database for new radio locations, messages, etc.
• Usage: Shorter intervals provide more real-time updates but may increase battery consumption slightly. Longer intervals are less resource-intensive but updates will be less frequent.

• “Setup BTECH Relay Service” / “Check Service Status” Buttons:

• Function: These buttons help you manage the crucial BTECH Relay Accessibility Service. The “Setup” button directly opens the Android settings page where you can enable/disable the service. The “Check Status” button verifies if the service is currently running.

7. Troubleshooting

If you encounter issues, refer to these common problems and solutions. For more detailed diagnostics, you may need to use adb logcat (see Section 7.5).

7.1. General Issues

• Plugin Crashes (especially on update/restart):

• Ensure you are using the latest version of the plugin.
• Check adb logcat for “FATAL EXCEPTION” messages around the time of the crash.

• Map Widget Not Appearing:

• The main relay toggle (top right in plugin view) must be active.
• Check adb logcat -s BtechRelay BtechRelayWidget for errors related to MapView or RootLayoutWidget during plugin start.

7.2. Virtual Contacts / Radio List Issues

• Radios Not Appearing / Not Broadcasting to Network:

1. Main Relay Toggle: Ensure the main relay toggle in the plugin view is ON.
2. BTECH App: Verify the BTECH smartphone app is running and properly configured with your radio.
3. CoT Broadcast Setting: In plugin settings, ensure “CoT Broadcast Enabled” is ON if you want to share radio locations with the network.
4. ATAK Network: Confirm your ATAK device has proper network connectivity (e.g., multicast is working on your Wi-Fi network).
5. Logcat: Check LocationDbPoller logs (adb logcat -s LocationDbPoller) for messages about data being read, timestamp issues, or errors sending broadcast intents.

7.3. Text Message / Chat Issues

• Messages from Radio Not Appearing in GeoChat / Not Rebroadcasting:

1. Main Relay Toggle: Ensure it’s ON.
2. Rebroadcast Setting: In plugin settings, ensure “Chat Bridge” is ON if you want to share these messages with the network.
3. Logcat: Check LocationDbPoller logs for message processing details and any rebroadcast attempts or errors.

7.4. Sending Messages / PTT (from Plugin UI) Failing

• Sending Text (“MSG” button) Fails:

1. Accessibility Service: This is the most common cause.

• Go to plugin settings and use the “Setup BTECH Relay Service” button to navigate to Android Accessibility settings.
• Ensure “BTECH Relay Service” is ON.
• Try toggling it OFF and then ON again.
• Grant any permissions it requests.

2. BTECH App: The BTECH app must be installed. Changes to the BTECH app’s UI by its developers can sometimes break the Accessibility Service’s automation.
3. Logcat: Check MessageBridgeActivity and BtechAccessibilityService logs (adb logcat -s MessageBridgeActivity BtechAccessibilityService) for errors.

• Voice PTT (“PTT” button) Fails:

1. Zello App: Ensure the Zello app is installed and configured to respond to standard PTT intents (com.zello.ptt.down, com.zello.ptt.up).

7.5. Key ADB Logcat Tags (for Advanced Troubleshooting)

If you are comfortable using Android’s ADB (Android Debug Bridge) tools, these logcat tags can provide detailed information:

• BtechRelay: For main UI operations and overall plugin coordination.
• LocationDbPoller: For data polling from the BTECH app, CoT/Chat generation, and dispatch logic.
• BtechAccessibilityService: For issues related to sending messages via the BTECH app’s UI.
• BtechRelayWidget: For the map widget status and potential errors.
• BtechRadialMenuMgr: If using the Radial Menu to send data.

8. Known Issues

• (This section can be populated if specific, persistent known issues are identified. Refer to the CHANGELOG.md or project issue tracker if available for the latest.)
• The reliability of sending messages via the Accessibility Service can be affected by updates to the BTECH app if its UI structure changes significantly.

9. Disclaimer

This plugin is designed for use with ATAK and BTECH radio hardware. Users are responsible for ensuring compliance with all local, state, and federal regulations regarding radio communications, software usage, and any related activities. The developers of this plugin assume no liability for misuse or non-compliance.