Documentation

/API




image


Interfacing with RF Power Nanny

You can communicate with RF Power Nanny and integrate it into your own code for custom functionality, your own UI or lab testing purposes. There are two main technology routes. If you have an Espressif device like an ESP32 variant, you can use ESP-NOW to interface with RF Power Nanny. For example, ESP32 boards with a display (sometimes called ESP32 terminal). The other route is to use a HTTP connection with common web technology using Python, JS or any language capable of HTTP communication.

image

HTTP API

Communication using HTTP is done using HTTP GET/POST requests and SSE (Server-Side Events).

The /power and /preferences endpoints will return information directly. The other two endpoints (/set and /request) will not return info back. These are the endpoints:

  • /power - HTTP_GET
  • /preferences - HTTP_GET
  • /set - HTTP_POST
  • /request - HTTP_POST
Power endpoint

The /power endpoint will return information directly in the response. It can be used from the browser to get the current power reading back as a JSON object. Or you can use it in your code to fetch a reading. We will publish some Python code on GitHub as a reference.

The response has the following format:

{
    "FWDMV" : float,            // Forward power in mV
    "REFMV" : float,            // Reflected power in mV
    "FREQ"  : int,              // Frequency in kHz
    "MNR"   : int,              // Measurement number
    "MS"    : unsigned long,    // Measurement time
    "BTEMP" : float,            // Bridge temperature
    "CTEMP" : float             // Controller temperature
}

see Power Formulas to convert mV to Watt or dBm

Preferences endpoint

The /preferences endpoint will return the current configuration settings as a JSON object.

Set endpoint

The /set endpoint can be used to configure RF Power Nanny, frontend or “Look Who’s Talking”. The response object does not contain information. Values are posted using http query parameters (key value pairs) like /request?key=value. Our advice is to post only one parameter (key value pair) per request. The following settings can be done using the /set endpoint:

peak_input

Value: True (1) or False (0)

True: use Peak power

False: use Average power

sampletime_input

Value: integer

Sample time in ms for probing max power value

scale_input

Value: integer (only affects frontend)

Scale 10, 25, 50 or 100

Scale 0 means auto

vcal_input

Value: float (affects frontend and external ESP32 devices)

Frequency independant calibration adjustment

fcal_input

Value: float (affects frontend and external ESP32 devices)

Frequency dependant calibration adjustment

rcal_input

Value: float (affects frontend and external ESP32 devices)

Resonance calibration adjustment for better accuracy in frequency range 5-15MHz

call_input

Value: string (only affects Look Who's Talking)

cannot contain ',' - replace comma's with '_.~'

Callsign

latlong_input

Value: string (only affects Look Who's Talking)

format lat_.~long

can not contain ',' - replace comma's with '_.~'

lat/long coordinates of the shack (location of Power Nanny)

mess_input

Value: string (only affects Look Who's Talking)

can not contain ',' - replace comma's with '_.~'

short message (max length 50 characters) for activity

Request endpoint

The /request endpoint can be used to trigger an action or to trigger a SSE response. The response object does not contain information. Most values are empty (the “key” is posted with an empty value). Use http query parameters (key value pairs) like /request?key=value. Our advice is to post only one parameter (key value pair) per request. The following settings can be done using the /set endpoint:

restart

Value: empty

Restart Power Nanny

getVersion

Value: empty

SSE response: version

Get firmware version

update

Value: string (filename without extension)

Update firmware with given filename

resetADC

Value: empty

Reset the on-board ADC

getExtDevAddress

Value: empty

SSE response: mac address

Get mac address of paired ESP-NOW device

unpair

Value: empty

Unpair paired ESP-NOW device

listenPairing

Value: empty

Start listening for pairing request from ESP-NOW device

endListenPairing

Value: empty

Stop listening for pairing request from ESP-NOW device

acceptPeer

Value: empty

Accept ESP-NOW peer

getSettings

Value: empty

SSE response: settings comma delimited

Format: name_extension, vCal_input, fCal_input, peak_input, sampletime_input, internet_access, scale_input, call_input, latlong_input, mess_input

Get current settings

Server Side Events (SSE)

RF Power Nanny will publish Server Side Events you can listen for. Below are the events you can listen for:

  • measurement
  • temperature
  • settings
  • ext_dev_addr
  • pairingRequest
  • version
measurement

Data: power

Format: Forward power mV, Reflected power mV, Frequency kHz

temperature

Data: temperature

Format: Controller temperature °C, Bridge temperature °C

settings

Data: current settings

Format: name_extension, vCal_input, fCal_input, peak_input, sampletime_input, internet_access, scale_input, call_input, latlong_input, mess_input

ext_dev_addr

Data: mac address of external ESP-NOW device

pairingRequest

Data: peer identifier string

version

Data: version string

Below you will find a JS example to catch these events and do something with the data. If there is any data, it can be accessed using e.data.


    source = new EventSource(nannyUrl + '/events')

    source.addEventListener('open', function(e) {
        console.log("SSE - sse open event")
    }, false)

    source.addEventListener('error', function(e) {
        console.log("SSE - sse error event")
    }, false)

    source.addEventListener('temperature', function(e) {
        console.log("SSE - sse temperature event")
    }, false)

    source.addEventListener('measurement', function(e) {
        console.log("SSE - sse measurement event")
    }, false);

    source.addEventListener('pairingRequest', function(e) {
        console.log("SSE - sse pairingRequest event")
    }, false);

    source.addEventListener('ext_dev_addr', function(e) {
        console.log("SSE - sse ext_dev_addr event")
    }, false);

    source.addEventListener('version', function(e) {
        console.log("SSE - sse version event")
    }, false);

    source.addEventListener('settings', function(e) {
        console.log("SSE - sse settings event")
    }, false);

//

Power Formulas

Measurement data is communicated in mV only. The receiving device or system should translate this in the form most suitable (also the receiving device is most likely more capable/powerful).

The formula for converting mV data to Watt is using calibration values. After production each RF Power Nanny is fine-tuned using a factory calibration process. The values are saved into permanent storage on the device. You can change the calibration settings if you like, there’s an option to reset to factory defaults in the APP.

Below you will find a JS implementation for converting received mV data to Watt and dBm. Here the “powerData” string is the comma delimited string received with a measurement event. The frequency received is in kHz and is converted to MHz as the power formula expects frequency in MHz. Note that for a specific frequency range (between 5-15MHz) the value is adjusted with an rCal (resonance calibration) value. This is used as an extra correction (adjustment) for slight deviations at these frequencies due to a cavity/resonance effect of the Power Nanny enclosure. It improves the accuracy for this frequency range.

JS example:


    let pArr = powerData.split(",")

    freq = (parseInt(pArr[2])/1000).toFixed(3)                              // frequency in kHz parsed as integer to MHz and then formatted with 3 decimals 

    fwdmV = parseFloat(pArr[0])
    refmV = parseFloat(pArr[1])

    let freqCorrection = fCal * Math.log10(parseInt(pArr[2])/1000)
    if ((freq >= 5) && (freq < 15)) {
        fwdWatt = Math.pow(10, (fwdmV - vCal + rCal + freqCorrection)/250)   // 10^((mV-vCal+rCal+(LOG(fMHz)*fCal))/250)
        refWatt = Math.pow(10, (refmV - vCal + rCal + freqCorrection)/250)
    } else {
        fwdWatt = Math.pow(10, (fwdmV - vCal + freqCorrection)/250)         // 10^((mV-vCal+(LOG(fMHz)*fCal))/250)
        refWatt = Math.pow(10, (refmV - vCal + freqCorrection)/250)
    }

    fwddBm = 10 * Math.log10(fwdWatt) + 30
    refdBm = 10 * Math.log10(refWatt) + 30

//

Python example:

# f=frequency (in MHz), mv=milliVolt, cal=calibration
def mvToWatt(f, mv, cal):
    if f >=5 and f < 15:
        return 10 ** ((mv-cal["vCal"]+cal["rCal"]+(math.log10(f)*cal["fCal"]))/250)    
    return 10 ** ((mv-cal["vCal"]+(math.log10(f)*cal["fCal"]))/250)

    #

Excel example:

Here column A holds the mV readings, B holds vCal/fCal calibration settings to play with and G is the column with frequency in MHz. Column J is used for rCal and only has values for frequencies between 5-15MHz (others have 0).

=10^(($A28-$B$3+$J28+(LOG($G28)*$B$4))/250)

ESP-NOW

When you want to use an external (display) device other than a computer or phone you can use any ESP32 powered terminal. The way RF Power Nanny can communicate with such a device is by using the ESP-NOW protocol. You can study the firmware of an ATOMS3R implementation to see how this can be done.

We will publish the firmware source code for the Power Nanny Extrenal Device Client for M5Stack ATOMS3R on GitHub as a reference: source code