FRStack WebAPI Service

Version 3.3.34

This version of FRStack provides REST APIs for RADIO, SLICE, UDP, PGXL AMP, SPE AMP, SteppIR Control
See how Node-Red users are leveraging FRStackWebApis by visiting nodered-hamradio on groups.io

Table of Contents

Version History
Upgrade .NET RPi or Linux
Install .NET RPi or Linux
Install .NET OSX

Install NodeRed
Run NodeRed RPi
Run NodeRed Ubuntu
Install NodeRed Libs

Upgrade FRStack Web APIs RPi
Install FRStack Web APIs RPi
Install FRStack Web APIs OSX

FRStack Web APIs Commandline run
FRStack Web APIs Service
FRStack Web APIs Service second instance

FRStackWebApi Configuration

RPi3 / RPi4 GPIO

FRStackWebApi APIs

Download links

Raspberry PI Version
Raspberry PI 64bit Version
Linux Version
OSX Version

Version History

V3.3.34.70 (OSX, Linux, RPi)

• Add Slice PAN API
• Add FILTERLOW FILTERHIGH set value using param= 3000
• Add Radio COPYTO COPYFROM APIs
• Add TGXL API
• Add TNF API
• Localization fix on Rest Frequency
• Bugfix FILTER set 1-9
• Bugfix Radio Tune, Tgxl Autotune detect logic

V3.3.33.63 (OSX, Linux, RPi)

• .Net 6.0 update

V3.3.32.62 (OSX, Linux, RPi)

• Remove console debug info

V3.1.31.60 (OSX, Linux, RPi)

• Add TX Slice API to the Active Slice and Slice A to H
• SteppIR add Follow Antenna selection API
• Fix SPE 1 support

V3.1.30.59 (OSX, Linux, RPi)

• RADIO INFO adds Transverter array - XVTRS
• SLICE BAND now accepts XVTRn where n is Transverter Index
• Document the installation of FRStack Web APIs Service second instance
• Node Red sample adds Radio Memory panel

V3.1.27.57 (OSX, Linux, RPi)

• Fix SPE Amp serial port .NET5 issue

V3.1.26.54 (OSX, Linux, RPi)

• Add Radio Memory REST API
• Add Radio SPOTS REST API
• Add Slice B tracks Slice A w/ rev direction feature

V3.1.25.53 (OSX, Linux, RPi)

• Enhance Radio Filter Sharpness API
• UDP Network Info - Adds RadioMox and ActiveRadioMox
• MOX state added to UDP Network and Web Socket information
• MOX state mapping to GPIO Output
• MOX input mapping to GPIO Input
• Fix UDP Broadcast on smaller ranges e.g. 192.168.1.255

V3.1.25.52 (OSX, Linux, RPi)

• Add Radio Filter Sharpness API

V3.1.24.50 (RPi only)

• Add GPIO APIs

V3.1.23.48 (OSX, Linux, RPi)

• Add CustomFunction feature
• Mode sets DAX ON / OFF feature
• Fixed Tune Detect logic
• Cleanup API return format

V3.1.20.10

• Add SteppIR retry for Home and Calibrate

V3.1.19.9

• Fix SteppIR bound client fix, command retry

V3.1.18.8

• Add web socket smeter data
• Fix smeter UDP

V3.1.16.7

• Radio Info Add NICKNAME, CALLSIGN, MODEL, SERIAL, VERSION, TXINHIBIT
• UDP info add App node
• SPE Add Info and Bug fixes
• SteppIR Add Info and Bug Fixes
• SWR Peak Hold and PGXL meter bug fixes

V3.1.16.2

• Initial Release

Upgrade to .NET Core 6.0 on RPi or Linux

If you are installing this service for the first time then advance to Install .NET Core 6.0

# remove the link to DotNet version 3
sudo rm /usr/bin/dotnet

# rename dotnet version 3 folder
sudo mv /opt/dotnet /opt/dotnet3

# now follow install instructions for **.NET Core 6.0**
# if you don't plan to use dotnet3 then you can remove the folder and files

Install .NET ASP.NET Core 6.0.8 on RPi or Linux

# You should be in your download folder: cd ~/Downloads/

wget <the dot net core download for your device>

# The following website has this info. https://dotnet.microsoft.com/download/dotnet/6.0

# Here is the current one for ARM32 devices
# https://download.visualstudio.microsoft.com/download/pr/cf567026-a29a-41aa-bc3a-e4e1ad0df480/0925d411e8e09e31ba7a39a3eb0e29af/aspnetcore-runtime-6.0.8-linux-arm.tar.gz

# Here is the current one for Linux x64 devices
# https://download.visualstudio.microsoft.com/download/pr/83695c9b-c954-459e-b9bf-2f1ac269e34e/1316ff4a6fe4c6916e7ecb3623d67cee/aspnetcore-runtime-6.0.8-linux-arm64.tar.gz
# https://download.visualstudio.microsoft.com/download/pr/5cc06c3a-4d8a-4fb2-8f7a-ecd23cd8c4e0/dd386c0e3a41ea54f459907c834acedf/aspnetcore-runtime-6.0.8-linux-x64.tar.gz


# From the Downloads folder, execute the following commands:

sudo mkdir -p /opt/dotnet
# for 32bit
sudo tar -zxf aspnetcore-runtime-6.0.8-linux-arm.tar.gz -C /opt/dotnet
# for 64bit
sudo tar -zxf aspnetcore-runtime-6.0.8-linux-arm64.tar.gz -C /opt/dotnet
sudo ln -s /opt/dotnet/dotnet /usr/bin

Install .NET ASP.NET Core 6 on OSX

The FRStackWebApiOsx.ZIP file contains com.mkcmsoftware.FRStackWebApi.plist which goes in the /Library/LaunchDaemon folder. This file assumes you have installed .NET and FRStackWebApi in folder indicated below.

# site to get .NET install script for OSX (if not already installed)
https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-install-script



# modify script file permissions to allow execution
chmod 755 dotnet-install.sh

# install command line to install .NET 5 runtime
./dotnet-install.sh --channel 6.0 --runtime aspnetcore

Install FRStackWebApi on OSX

# Expand FRStackWebApiOsx.ZIP in the /usr/local/frstack
sudo chown root /usr/local/frstack/*
sudo chmod 644 /usr/local/frstack/*

# load daemon
sudo launchctl load /Library/LaunchDaemons/com.mkcmsoftware.FRStackWebApi.plist

# manually start
sudo launchctl start com.mkcmsoftware.frstackwebapi   

# manually stop
sudo launchctl stop com.mkcmsoftware.frstackwebapi   

# force unload daemon
sudo launchctl unload /Library/LaunchDaemons/com.mkcmsoftware.FRStackWebApi.plist

# command to check on daemon process id and exit error code
sudo launchctl list | grep com.mkcm

# open console to view logs
open /System/Applications/Utilities/Console.app
# select log tab on lefthand menu
# look for frstack.log and frstack_err.log

Install Node Red on RPi or Linux (Ubuntu use here)

Your version of RPi Linux may already have Node-Red installed. Check before downloading another copy.

RPi See https://nodered.org/docs/getting-started/raspberrypi

# RPi
bash <(curl -sL https://raw.githubusercontent.com/node-red/linux-installers/master/deb/update-nodejs-and-nodered)

For Ubuntu V20 you can use the Ubuntu Software Application, search node-red then install.

Default address for Node Red is http://hostname:1880

Running Node Red on RPi

On pi to run node red in terminal use:

node-red

The following commands are provided to work with the service:

node-red-start - this starts the Node-RED service and displays its log output. Pressing Ctrl-C or closing the window does not stop the service; it keeps running in the background
node-red-stop - this stops the Node-RED service
node-red-restart - this stops and restarts the Node-RED service
node-red-log - this displays the log output of the service

If you want Node-RED to run when the Pi is turned on, or re-booted, you can enable the service to autostart by running the command:

sudo systemctl enable nodered.service

To disable the service, run the command:

sudo systemctl disable nodered.service

Running Node Red on Ubuntu

Node-Red is a running service after Snap installation on Ubuntu. If you install outside of snap then use RPi style of commands.

The following commands are provided to work with the service:

sudo snap start node-red - this starts the Node-RED service and displays its log output. Pressing Ctrl-C or closing the window does not stop the service; it keeps running in the background
sudo snap stop node-red - this stops the Node-RED service
sudo snap restart node-red - this stops and restarts the Node-RED service
sudo snap logs node-red - this displays the log output of the service

If you want Node-RED to run when the Pi is turned on, or re-booted, you can enable the service to autostart by running the command:

sudo snap enable node-red

To disable the service, run the command:

sudo snap disable node-red

Now install Node-Red UI library from Manage Palette menu

• node-red-dashboard
• node-red-contrib-ui-level
• node-red-contrib-ui-led

Upgrading FRStack WebAPI on RPi or Linux

If this is your first install of FRStackWebApi then proceed to Install FRStack WebAPI on RPi or Linux

sudo systemctl stop FRStackWebApi 
sudo mv /usr/local/frstack /usr/local/frstack_old

# now follow install instructions above
# Note: you do not have to perform the Install FRStackWebApi as service since that was already performed in the prior install

# Remember to merge your config changes into the new app.settings file

# now start the new version of the service
sudo systemctl start FRStackWebApi 

Install FRStack WebAPI on RPi or Linux

sudo mkdir -p /usr/local/frstack
cd /usr/local/frstack

# for RPi
sudo wget https://www.mkcmsoftware.com/download/FRStackWebApiRPi.zip
# for RPi 64
sudo wget https://www.mkcmsoftware.com/download/FRStackWebApiRPi64.zip
# for Linux x64
sudo wget https://www.mkcmsoftware.com/download/FRStackWebApiLinux.zip

sudo unzip FRStackWebApiRpi
# to update specific files from ZIP add the name of the file(s) after the ZIP filename
# for example: sudo unzip FRStackWebApiRpi.zip FRStackWebApi.dll frstackNodeRedV108.json

Run FRStack WebAPI from commandline on all OS

cd /usr/local/frstack
dotnet FRStackWebApi.dll --urls "http://*:5025"

Install FRStackWebApi as service on RPi

sudo cp FRStackWebApi.service /lib/systemd/system
sudo systemctl daemon-reload 
sudo systemctl enable FRStackWebApi

Note the FRStackWebApi.service contains the port the API will listen on 5025

[Unit]
Description=FRStack Web APIs
After=network.target
 
[Service]
Type=notify
WorkingDirectory=/usr/local/frstack
ExecStart=/usr/bin/dotnet FRStackWebApi.dll --urls "http://*:5025"
Restart=on-failure
 
[Install]
WantedBy=multi-user.target

Start FRStackWebApi service on RPi

sudo systemctl start FRStackWebApi 

View FRStackWebApi service status on RPi

systemctl status FRStackWebApi

Tail FRStackWebApi service log on RPi

journalctl --unit FRStackWebApi --follow

Stop FRStackWebApi service on RPi

sudo systemctl stop FRStackWebApi 
systemctl status FRStackWebApi 

Cleaning up FRStackWebApi service on RPi

Ensure service is stopped

sudo systemctl stop FRStackWebApi 

Disable the FRStackWebApi service on RPi

sudo systemctl disable FRStackWebApi 

Remove and reload SystemD

sudo rm FRStackWebApi.service /lib/systemd/system/FRStackWebApi.service 
sudo systemctl daemon-reload 

Verify SystemD is no longer aware of the FRStackWebApi service

Empty is what we want here

systemctl --type service |& grep FRStackWebApi

Install second instance of FRStackWebApi as service on RPi

sudo cp FRStackWebApi2.service /lib/systemd/system
sudo systemctl daemon-reload 
sudo systemctl enable FRStackWebApi2

Note the FRStackWebApi2.service contains the port the API will listen on 5026

[Unit]
Description=FRStack Web APIs 2
After=network.target
 
[Service]
Type=notify
WorkingDirectory=/usr/local/frstack2
ExecStart=/usr/bin/dotnet FRStackWebApi.dll --urls "http://*:5026"
Restart=on-failure
 
[Install]
WantedBy=multi-user.target

Note the pattern of additional instances can be continued by changing the suffix of 2 to 3 and so on. The install folder, .service filename, description, working directory and port number will be incremented. The commands are identical except for the suffix of your new instance number. For example FRStackWebApi becomes FRStackWebApi2.

Sample Node Red Script

frstackNodeRedV108.json

FRStackWebApi Configuration

The appSettings.json file contains the startup configuration for the service.

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
      }
    },
  "AllowedHosts": "*",

  "SvcConfig": {
    "AutoConnect": "true",
    "initRadioName": null, // optionally configure the default radio name here to autoconnect to
    "initClientName": null, // optionally configure the default client name to bind to
    "MRUMatchDelta": "0.000999",
    "FollowActiveSlice": "true",
    "MuteOthersOnSliceActive": "true",
    "EnableTxOnSliceActive": "true",
    "TempUnitInF": "true",
    "PgxlTuneStandby": "true", // this will set AMP to STANDBY when TUNE is activated
    "PgxlModeRestore": "true", // this will return AMP to OPERATE after TUNE complete
    "PgxlRadioMaxPower": "50", // this is MAX radio power level when AMP is OPERATE
    "PgxlRadioStandbyPower": "100", // this is MAX radio power level when AMP is STANDBY
    "PGXLOnAntenna": "0", // 0 or 1 or 2; 0 for both, 1 for ANT1, 2 for ANT2
    "RCATXACCTuneDisable": "false", 
    "RCATX1TuneDisable": "false",
    "RCATX2TuneDisable": "false",
    "RCATX3TuneDisable": "false",
    "RadioTuneModeDetect": "false", // this is set true if you want to detect a Radio Tune button push, remember to set TX Delay on radio
    "SPEComPort": "", // this is the Serial device for SPE AMP Control port (Not the CAT port)
    "SPETuneStandby": "false", // this will set SPE to STANDBY when TUNE is activated
    "SPEModeRestore": "false", // this will return SPE to OPERATE after TUNE complete
    "SPEOnAntenna": "0", // 0 or 1 or 2; 0 for both, 1 for ANT1, 2 for ANT2
    "SPEUseDTR": "false", // this will set DTR to power up amp
    "SPEProtocolV1": "false", // this is set true for SPE V1 amps
    "SPEAutoOpen": "false", // this is set true to OPEN SPE after connecting to radio
    "SteppIRComPort": "", // port,baud,parity,stop,FollowAntInt,EnabledBool,SyncManualBool,AntTxInhibitInt,AntennaType eg. "/dev/ttyUSB0,9600,None,One,0,true,true,1,1"
    "FDXProtect": "false,false,false,false,false,false", // enabled,ant1,ant2,rxa,rxb,wide
    "UDPSettings": "false,255.255.255.255,12070,false,127.0.0.1,12071,false,127.0.0.1,12072,false,127.0.0.1,12073", // enabled,IPADDR,PORT, enabled,IPADDR,PORT, enabled,IPADDR,PORT, enabled,IPADDR,PORT 
    "UDPMeterSettings": "false,255.255.255.255,12270,false", // enabled,IPADDR,PORT,SMeterEnabled
    "ModeSetsDax": "0", // 0 - Disable, 1 - turn DAX on when mode is DIGL/H, 2 - turn DAX off if not DIGL/H, 3 - both
    "CustomFunctions": "",
    //
    // Set GPIO Logical Pins by string of numbers 
    // where 0 is not set
    // "1" - Input
    // "2" - Input Pull down
    // "3" - Input Pull up
    // "4" - Output
    // "5" - Output set low on start
    // "6" - Output set high on start
    //   GPIO        0000000000111111111122222222
    //   PINS #s     0123456789012345678901234567
    "GPIOConfig": "", // RPi3 or RPi4 GPIO configuration 
    // MOX In, Out values using GPIO numbers 0-27
    "MOXInOut": "",
    //
    // Sample MOX in on 20 and MOX output on 13
    //   GPIO        0000000000111111111122222222
    //   PINS #s     0123456789012345678901234567
    //"GPIOConfig": "0000000000000500000020000000",
    //"MOXInOut": "20,13" 
    //
    "SliceTrackEnabled": false, // Slice B tracks slice A Freq
    "SliceTrackRev": false // Tracking freq in reverse, ignored if SliceTrackEnabled is false
  }
}

//SteppIRComPort comma delimited settings 
//    COMPort,
//    Baudrate, usually 9600 or 19200
//    Parity, - None, Odd, Even
//    StopBits, - One or Two
//    FollowAntInt, 0 - 8, 0 means TX Slice or 1-8 is for slice letter A thru H for bound client 
//    EnabledBool, - False or True, True means enable this feature
//    SyncManualBool, - False or True, True means manual Freq sync
//    AntTxInhibitInt - 0 - 3, 0 - no TX Inhibit, 1 - ANT1, 2 - ANT2, 3 - Both ANT
//    AntennaType, 0 to 3, 0 = Beam using CAT, 1=Vertical using CAT, 2=Bean no CAT, 3=Vertical no CAT

RPi3 or RPi4 GPIO configuration

For RPi3 and RPi4 Devices you can configure the GPIO pin for use by the GPIO Rest API.

On boot all GPIO are in INPUT mode, GPIO 0-8 have pull-ups to 3V3 enabled, GPIO 9-27 have pull-downs to 0V enabled.

During boot a sequence of optional configurations can set GPIO. See links below:

BCM2835-ARM-Peripherals.pdf
pin-configuration
config-txt GPIO

FRStackAPI appSettings GPIOConfig

Set GPIO Logical Pins by string of numbers

• where 0 is not set
• "1" - Input
• "2" - Input Pull down
• "3" - Input Pull up
• "4" - Output
• "5" - Output set low on start
• "6" - Output set high on start

// GPIO        0000000000111111111122222222
// PINS #s     0123456789012345678901234567
"GPIOConfig": "0000022000000500000500000000"

// this sample shows 
// inputs 5 and 6 w/ pull down and 
// outputs 13 and 19 set to low (0) on service start


// This Sample MOX in on 20 and MOX output on 13
//   GPIO        0000000000111111111122222222
//   PINS #s     0123456789012345678901234567
"GPIOConfig": "0000000000000500000020000000",
"MOXInOut": "20,13" 

This link will jump to the GPIO Rest APIs:
GPIO Rest API

FRStackWebApi APIs

FRStack Commands
http://localhost:5025/FRStack/?param=

Radio Commands
http://localhost:5025/Radio/?param=

Slice / Active Slice Commands
http://localhost:5025/ActiveSlice/?param=
To target specific slice letter use
http://localhost:5025/Slice//?param=
http://localhost:5025/ActiveSlice/?letter=&param=
To target TX slice letter use
http://localhost:5025/Slice/TX/?param=
To target slice index use
http://localhost:5025/ActiveSlice/?index={0-7}&param=

Radio Memory Commands
http://localhost:5025/RadioMem/?param=

SPE Amplifier Slice Commands
http://localhost:5025/SPEAMP/?param=

SteppIR Commands
http://localhost:5025/STEPPIR/?param=

Note:

• FREQANT, FREQE, SYNC can only be used when CAT cable is not used.
• OPEN with param=1 will connect to COM port then send the 'R' Wake / Turn on Serial frequency update command
• RETRACT will send 'U' Turn off Serial frequency update then 'S' Home antenna

TGXL Commands
http://localhost:5025/TGXL/?param=

GPIO Commands
http://localhost:5025/GPIO/ - Read IO Pin Value

http://localhost:5025/GPIO//{0_or_1} - Write Output Pin Value

http://localhost:5025/GPIO/?param=

JSON object returned

{
    "pin": "13,19,26",  // pin list
    "val": "110",       // binary list of values       
    "ival": 6           // decimal value for pin list  
}

Meter information over WebSocket

http://localhost:5025/ws/meters

Json Meter Data returned

{
 "station":"6600M",
 "callsign":"W3II",
 "nickname":"6600M",
 "ipaddr":"192.168.1.202",
 "meters":{
    "+13.8A":"14.2",
    "PATEMPC":"32.1",
    "FWDPWR":"0.0",
    "REVPWR":"0.0",
    "SWR":"1.0",
    "AMP PWR":"0",
    "AMP ID":"0",
    "AMP SWR":"1.1",
    "AMP TEMPC":"30.2",
    "AMP TEMPF":"86.3",
    "PATEMPF":"89.8",
    "MOX":"0"}
}

Json S-Meter Data returned

{
 "machinename":"rpi4svr",
 "callsign":"W3II",
 "nickname":"6600M",
 "ipaddr":"192.168.1.202",
 "smeters":[  // 8 smeter objects for slice index 0 - 7 
   { // slice 0
     "letter":"A",
     "client":"6600M",
     "dbm":-67,  // -150 dbm to 27 dbm
     "sunit":"S9"
   },
   { // slice 1
     "letter":null, // this is the 2nd slice which is not present
     "client":null,
     "dbm":0,
     "sunit":null
   }, 
   // ... remaining Slice 2-7, 6 slice slots follow ...
  ]
}

Slice information contains an INDEX property which can be used to index into the smeter array.

Assign FTDI serial cable to fixed name

From a terminal window:

1. find out what's on ttyUSB:

pi@raspberrypi:~ $ dmesg | grep ttyUSB 
[142617.031424] usb 1-1.4: FTDI USB Serial Device converter now attached to ttyUSB0
Take note of the node numbers: In this case 1-1.4

2. list all attributes of the devices (in this case USB0 and USB1):

pi@raspberrypi:~ $ udevadm info --name=/dev/ttyUSB0 --attribute-walk
...
looking at parent device '/devices/platform/scb/fd500000.pcie/pci0000:00/0000:00:00.0/0000:01:00.0/usb1/1-1/1-1.4':
    KERNELS=="1-1.4"
    SUBSYSTEMS=="usb"
    DRIVERS=="usb"
    ATTRS{devspec}=="(null)"
    ATTRS{quirks}=="0x0"
    ATTRS{product}=="USB Serial Converter"
    ATTRS{avoid_reset_quirk}=="0"
    ATTRS{devnum}=="20"
    ATTRS{idProduct}=="6001"
    ATTRS{speed}=="12"
    ATTRS{ltm_capable}=="no"
    ATTRS{bConfigurationValue}=="1"
    ATTRS{maxchild}=="0"
    ATTRS{devpath}=="1.4"
    ATTRS{manufacturer}=="FTDI"
    ATTRS{bDeviceSubClass}=="00"
    ATTRS{bNumInterfaces}==" 1"
    ATTRS{busnum}=="1"
    ATTRS{urbnum}=="143382"
    ATTRS{bcdDevice}=="0600"
    ATTRS{bMaxPacketSize0}=="8"
    ATTRS{bDeviceProtocol}=="00"
    ATTRS{bMaxPower}=="44mA"
    ATTRS{serial}=="FT8YXPRB"
    ATTRS{bNumConfigurations}=="1"
    ATTRS{tx_lanes}=="1"
    ATTRS{configuration}==""
    ATTRS{rx_lanes}=="1"
    ATTRS{removable}=="unknown"
    ATTRS{bmAttributes}=="a0"
    ATTRS{version}==" 2.00"
    ATTRS{bDeviceClass}=="00"
    ATTRS{authorized}=="1"
    ATTRS{idVendor}=="0403"
...

Look at the tree leaf matching the node name from the prior step. In this case ..../usb1/1-1/1-1.4 You have to look at a unique differentiator between the devices. In most cases you can use the idVendor field (0403 in this case) or the idProduct field (6001 in this case) as the differentiator between the two devices. In case the vendor ID is the same, you can use the serial number of the two devices.

3. We are now going to create a new USB device linked to the unique information we have. Create a file /etc/udev/rules.d/10-usb-serial.rules with rules for all USB devices in it:

pi@raspberrypi:~ $ sudo nano /etc/udev/rules.d/10-usb-serial.rules

Type the following in the nano editor and then save the file (ctrl-o) and (ctrl-x):

SUBSYSTEM=="tty", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", ATTRS{serial}=="FT8YXPRB",  SYMLINK+="ttyUSB_SIR"

4. Load the new rule:

pi@raspberrypi:~ $ sudo udevadm trigger

5. Verify this works:

pi@raspberrypi:~ $ ls -l /dev/ttyUSB*
crw-rw---- 1 root dialout 188, 0 Aug  8 15:24 /dev/ttyUSB0
lrwxrwxrwx 1 root root         7 Aug  8 14:22 /dev/ttyUSB_SIR -> ttyUSB0

As you see we still have the existing USB0 device, but we also have a symbolic link to device that are match the correct hardware. These symbolic links will be created at each reboot or when the USB device is plugged into an USB port.

6. Now change the device for the FTDI cable to ttyUSB_SIR

Copyright � MKCM Software, LLC 2014-22