Categories
BrandMeister

Using the BrandMeister API

Here is my approach to using talkgroups and my AnyTone radio on BrandMeister, as well as using the BrandMeister SelfCare account to check the status of static and auto-static talkgroups right in the browser. There’s also some commands that can be used in any Linux Terminal, and they also should work in Windows Subsystem for Linux or even a router shell.

  1. Basic setup
  2. The role and function of the hotspot
  3. Using the BrandMeister API
    1. Checking current talkgroup’s status in a browser
    2. Running commands in Terminal

1. Basic setup

  • I have set up the main talkgroups I’m interested in as static talkgroups via BrandMeister Self Care.
  • I use a duplex hotspot and the channels for the static talkgroups are distributed between time slots 1 and 2. There are multiple talkgroups set up as static on each time slot.
  • In my radio’s codeplug, I have separate channels for each talkgroup, and I set up a single zone that contain multiple static talkgroup channels. Each channel has its own Receive Group. That way, when I have a specific channel selected, I receive transmissions only from the talkgroup associated with it, and when I press PTT, my transmission goes out only to that selected talkgroup.
  • Most of the time, I keep my radio in Digital Monitor mode. When I want to listen to a specific talkgroup, I turn off Digital Monitor mode and switch to that talkgroup’s channel.

2. The role and function of the hotspot

  • The hotspot itself serves as just an interface converter and a proxy for commands and traffic. For example, if you transmit a group call to TG 4000 from your radio, the hotspot will receive it (as long as the channel is free), decode it, and send it to the BrandMeister server, which is where all the real work takes place.
  • Sometimes—for example, during nets—I don’t want multiple talkgroups sharing a time slot, so I need to remove the static talkgroups from that time slot and add only the one I’m interested in. After I’m done with that one talkgroup, for example, when the net is finished, I return everything to the initial state. These are tasks that can be automated, which I’ll describe below.
  • I don’t like to keep the Pi-Star Admin dashboard open all the time in my browser, and I don’t use a Nextion display (yet), but it’s possible to create shortcuts on a computer’s desktop that mimic the functions of the Pi-Star Admin dashboard, which I’ll also describe below.
  • For simplex hotspots, BrandMeister always sees the time slot as 0 (zero). For duplex hotspots, it will be 1 or 2. For more info, see the BrandMeister Wiki article: API/Halligan API.

3. Using the BrandMeister API

In order to use the features available via the BrandMeiser API, you need to get a BrandMeister API key. You should make a note of it as you can view it in BrandMeister SelfCare only once, and you’ll need it for the automation commands described below. (You also can use it to enable the BrandMeister Manager Module in Pi-Star for your hotspot.) See the instructions for getting a BrandMeister API Key on the Pi-Star Wiki: PI-Star integration with BrandMeister API.

Once you have a BrandMeister API key, you can monitor your hotspot’s settings on the BrandMeister dashboard where you can see which talkgroups are static or auto-static. You can use this to verify things while you’re testing your automation commands and scripts:

  1. Log into your BrandMeister SelfCare account: https://brandmeister.network/
  2. Find the My hotspots option in the BrandMeister menu:
    • In a wide browser window, it’s the open left panel.
    • On a mobile device or in a narrower browser window, it can be opened by clicking the top left Menu button. See image below: looks like three lines stacked on each other, and is commonly called the “hamburger” button.
  3. Click My hotspots to open a list of your hotspots, and then click the CCS7 ID associated with the hotspot you want to look at. See image below.
  4. In the hotspot Settings window that opens, scroll down to the Static Talkgroups section to see which talkgroups are static or auto-static. See image below.
    Note: It can take a minute or so for an auto-static talkgroup to show up in the Static Talkgroups list (sometimes you must refresh to see the change).
  5. In a desktop browser window, if you point your mouse cursor at a listed auto-static talkgroup, you’ll see a tooltip identifying it as “Auto Static.” See image below.
    Note: The rest of the tooltip hasn’t been updated to accurately reflect how the auto-static feature is working as of Mar 2019. The tooltip should read: “This talkgroup was set automatically as auto-static due to it being the last talkgroup keyed up.”
BrandMeister Hamburger button
2) The hamburger button
CCS7 ID for your hotspot
3) Click the CCS7 ID for your hotspot
Static Talkgroups section
4) Scroll down to the Static Talkgroups section
Auto Static tooltip
5) Point your mouse cursor at a listed auto-static talkgroup

3-1. Checking current talkgroup’s status in a browser

Once you have your BrandMeister SelfCare account set up, you can use the “My hotspots” ID for your active hotspot to check the status of static and auto-static talkgroups right in your browser using this URL:

https://api.brandmeister.network/v1.0/repeater/?action=profile&q=[My hotspot ID]

Status of static and auto-static talkgroups shown in browser
  • My hotspots ID parameter: Replace [My hotspot ID] with the actual ID for your hotspot, which is typically your CCS7 ID or an extended SSID (ESSID).
  • Hint: Optionally, you can make the display of the results look nicer using a browser extension such as Pretty JSON, which is available in the Chrome Web Store. You could use this to make a custom display for your hotspot, or you could retrieve Last Heard and display it customized to look how you want.

3-2. Running commands in Terminal

You can use these commands in any Linux Terminal. They also should work in Windows Subsystem for Linux or even a router shell. A few general notes:

  • BM API Key parameter: Replace [BM API Key] with your actual API Key. Don’t delete the colon (:) or the single quotation marks (‘).
  • URL parameter: Don’t delete the double quotation marks (“).
  • My hotspots ID parameter: Replace [My hotspot ID] with the actual ID for your hotspot, which is typically your CCS7 ID or an extended SSID (ESSID).
  • Slot parameter: Replace [0/1/2] with the actual time slot number. For simplex hotspots, BrandMeister always sees the time slot as 0 (zero). For duplex hotspots, it will be 1 or 2.
  • Reference document: GitHub > AndyTaylorTweet > Pi-Star_Binaries_sbin/pistar-bmapi

3-2.i. Drop the current QSO

curl -s --user '[BM API Key]:' "https://api.brandmeister.network/v1.0/repeater/setRepeaterDbus.php?action=dropCallRoute&slot=[0/1/2]&q=[My hotspot ID]"

3-2.ii. Drop all dynamic talkgroups

If you are stuck on a talkgroup, you can use this command together with the Drop the current QSO command to get out. If you make a desktop shortcut for these commands, it takes just a few seconds to drop it.

curl -s --user '[BM API Key]:' "https://api.brandmeister.network/v1.0/repeater/setRepeaterTarantool.php?action=dropDynamicGroups&slot=[0/1/2]&q=[My hotspot ID]"

3-2.iii. Add static talkgroup

curl -s --user '[BM API Key]:' --data "talkgroup=[Talkgroup #]&timeslot=[0/1/2]" "https://api.brandmeister.network/v1.0/repeater/talkgroup/?action=ADD&id=[My hotspot ID]"

3-2.iv. Remove static talkgroup

curl -s --user '[BM API Key]:' --data "talkgroup=[Talkgroup #]&timeslot=[0/1/2]" "https://api.brandmeister.network/v1.0/repeater/talkgroup/?action=DEL&id=[My hotspot ID]"

3-2.v. Drop all static talkgroups

For this one, you’ll need to install an additional program: jq. On Ubuntu- and Debian-compatible Linux distributions, it can be installed using the command:
apt install jq.

Then you can use a large single command to drop all static talkgroups:
curl -s "https://api.brandmeister.network/v1.0/repeater/?action=profile&q=[My hotspot ID]" | jq -r '.staticSubscriptions[]|[.talkgroup, .slot] | @tsv' | while IFS=$'\t' read -r talkgroup slot; do curl -s --user '[BM API Key]:' --data "talkgroup=$talkgroup×lot=$slot" "https://api.brandmeister.network/v1.0/repeater/talkgroup/?action=DEL&id=[My hotspot ID]"; done

An explanation:

  • curl -s "https://api.brandmeister.network/v1.0/repeater/?action=profile&q=[<span class="textred">My hotspot ID</span>]"
    retreives the list of connected TGs in json format.
  • jq -r '.staticSubscriptions[]|[.talkgroup, .slot] | @tsv'
    extracts each TG and timeslot and passes it via environment variables further.
  • while ... done
    enumerates each TG.
  • curl -s --user '[<span class="textred">BM API Key</span>]:' --data "talkgroup=$talkgroup&timeslot=$slot" "https://api.brandmeister.network/v1.0/repeater/talkgroup/?action=DEL&id=[<span class="textred">My hotspot ID</span>]"
    sends actual unlink command.

3-2.vi. Putting it all together in a script

Using the above commands, you can create a shell script (.sh) to
perform tasks on a schedule using Cron (Linux scheduler). For example,
if you want to participate in the Colorado HD net, which is on talkgroup
31088 on Tuesdays (day # 2) from 7:30 PM to 10:50 PM Mountain Time, you
can create one script to drop all other talkgroups, including dynamic,
and add 31088, and a second script to restore things to how they were
after the net is over.

If you are working in Pi-Star as a regular user:

  • 25 21 * * 2 /home/pi-star/tgcoloradohd.sh
  • 50 23 * * 2 /home/pi-star/tgrestoreall.sh

Or, if you are working as the root user:

  • 25 21 * * 2 /root/tgcoloradohd.sh
  • 50 23 * * 2 /root/tgrestoreall.sh

In these examples, the time is converted to Eastern Time:

  • tgcoloradohd.sh – The first script runs at 7:25 PM Mountain Time (19:25 Mountain Time or 21:25 Eastern Time).
  • tgrestoreall.sh – The second script runs at 10:50 PM Mountain Time (21:50 Mountain Time or 23:50 Eastern Time).

A few notes:

  • The tgcoloradohd.sh script should include:
    • Drop all dynamic talkgroups.
    • Remove static talkgroup for each of the static talkgroups that are set up.
      Note: It’s ok to run this for a talkgroup as long as it’s not connected.
    • Add static talkgroup to add Colorado HD 31088.
  • The tgrestoreall.sh script should include:
    • Drop all dynamic talkgroups.
    • Add static talkgroup to add all your favorite talkgroups as static.
  • For more info about Cron, see Cron (Wikipedia).
  • You also can use the Pi-Star crontab, but your settings might be deleted the next time Pi-Star updates, so make sure to check that.

Here’s an example of tgcoloradohd.sh for a simplex hotspot (timeslot=0), which drops two static talkgroups (31075 and 25701), adds talkgroup 31088, and finally drops all dynamic talkgroups:

#!/bin/bash
curl -s --user '[BM API Key]:' --data "talkgroup=31075&timeslot=0" "https://api.brandmeister.network/v1.0/repeater/talkgroup/?action=DEL&id=[My hotspot ID]"
curl -s --user '[BM API Key]:' --data "talkgroup=25701&timeslot=0" "https://api.brandmeister.network/v1.0/repeater/talkgroup/?action=DEL&id=[My hotspot ID]"
curl -s --user '[BM API Key]:' --data "talkgroup=31088&timeslot=0" "https://api.brandmeister.network/v1.0/repeater/talkgroup/?action=ADD&id=[My hotspot ID]"
curl -s --user '[BM API Key]:' "https://api.brandmeister.network/v1.0/repeater/setRepeaterTarantool.php?action=dropDynamicGroups&slot=0&q=[My hotspot ID]"

And here’s an example of tgrestoreall.sh, also for a simplex hotspot:

#!/bin/bash
curl -s --user '[BM API Key]:' --data "talkgroup=31088&timeslot=0" "https://api.brandmeister.network/v1.0/repeater/talkgroup/?action=ADD&id=[My hotspot ID]"
curl -s --user '[BM API Key]:' --data "talkgroup=31075&timeslot=0" "https://api.brandmeister.network/v1.0/repeater/talkgroup/?action=ADD&id=[My hotspot ID]"
#curl -s --user '[BM API Key]:' --data "talkgroup=25701&timeslot=0" "https://api.brandmeister.network/v1.0/repeater/talkgroup/?action=ADD&id=[My hotspot ID]"

Creative Commons License
This work is licensed under a
Creative Commons Attribution-ShareAlike 4.0 International License.