TCPIP interlock - flexradio/smartsdr-api-docs GitHub Wiki

The SmartSDR Interlock engine ensures that the radio does not transmit at inappropriate times. Interlock is used both for internal switching in the radio as well as for accessories such as amplifiers and antennas. There are two key ways to access interlock in the FLEX-6000 from an API standpoint. First, if the operator has plugged in something to the ACC port (DB15) on the radio or into the TX REQ line, then commands can be issued to tell the radio that these ports are to be factored into the interlock. A polarity in addition to an enable/disable are supported for the two interlocks. Essentially, when the interlock line is active (ACC or TX_REQ), the radio can enter the transmit mode, but will not supply transmit power to the output port until the interlock line is releases.

Some products that run external to the radio may prefer to negotiate interlock in software through the API entirely. The commands that govern the software interlock for external devices are interlock create, ready, enable, disable and remove. For these devices, a dynamic interlock per device can be created and then set and cleared entirely using the API. This means that no wires between the transceiver and the amplifier or antenna controller other than the ethernet cable would be required.

Hardware interlocks are handled through the ACC and TX_REQ lines on the rear of the transceiver. The API commands for these interlocks simply enable and disable the interlock and set the polarity (active high or low) for the interlock

Set the transmit timeout value. If the radio is in transmit beyond this point, the radio will automatically unkey

C[D]<seq_number>|interlock timeout=<timeout_ms>

<timeout_ms>  = the timeout value in milliseconds (60000 for one minute, for example)

Example:

C21|interlock timeout=20000

See Response Format for details on the format of the response messages from the radio

Responses

Response Example:

R21|0|

The TXREQ lines are designed to stall or prevent transmit when external hardware is not ready for RF. There are two hardware TXREQ lines on the FLEX-6000 Signature Series radios, one as an RCA connector and the other as a line on the DB-15 accessory connector. Each TXREQ line may be independently enabled or disabled and each line has a polarity setting. The polarity determines the setting (high or low) in which transmit is OK.

C[D]<seq_number>|interlock acc_txreq_enable=<T|F>

<T|F>      = A 'T' or an 'F' indicating whether this TXREQ port is enabled

Note that rca_txreq_enable may be substituted for the RCA TXREQ line

Example:

C21|interlock acc_txreq_enable=T

See Response Format for details on the format of the response messages from the radio

Responses

Response Example:

R21|0|

C[D]<seq_number>|interlock acc_txreq_polarity=<T|F>

<T|F>      = A 'T' or an 'F' indicating the line state for "transmit OK."  So an 'F' would indicate that it is OK to transmit if the line is 0 Volts

Note that rca_txreq_polarity may be substituted for the RCA TXREQ line

Example:

C21|interlock rca_txreq_polarity=F

See Response Format for details on the format of the response messages from the radio

Responses

Note the lowercase x is to be substituted with 1, 2, or 3

C[D]<seq_number>|interlock tx<1|2|3>_enabled=<T|F>

<T|F>      = A 'T' or an 'F' indicating the line state for "transmit OK."  So an 'F' would indicate that it is OK to transmit if the line is 0 Volts

Example:

C21|interlock tx1_enabled=F

See Response Format for details on the format of the response messages from the radio

Responses

Note the lowercase x is to be substituted with 1, 2, or 3

C[D]<seq_number>|interlock tx<1|2|3>_delay=<timeout_ms>

<timeout_ms> = delay value in milliseconds

Example:

C21|interlock tx1_delay=1000

See Response Format for details on the format of the response messages from the radio

Responses

C[D]<seq_number>|interlock acc_tx_enabled=<T|F>

<T|F>      = A 'T' or an 'F' indicating the line state for "transmit OK."  So an 'F' would indicate that it is OK to transmit if the line is 0 Volts

Example:

C21|interlock acc_tx_enabled=F

See Response Format for details on the format of the response messages from the radio

Responses

C[D]<seq_number>|interlock acc_tx_delay=<timeout_ms>

<timeout_ms> = delay value in milliseconds

Example:

C21|interlock acc_tx_delay=1000

See Response Format for details on the format of the response messages from the radio

Responses

Ethernet Interlocks, those created and controlled over the Ethernet, must be created and controlled using API commands and statuses. The general sequence for Ethernet interlocks are as follows:

1. Device connects to radio as a client
2. Device creates an interlock for itself using interlock create
3. Amplifier interlocks immediately become not ready, Antenna interlocks start as ready
4. Device waits for a PTT_REQUESTED state to be emitted from interlock
5. Device becomes ready internally
6. Device sends a interlock ready command to the radio

Example interaction between client and radio:

(1) '''C2|interlock create type=amp name=KZX-2500 serial=111-2500-111 valid_antennas=ANT1,ANT2' (2) R2|0|1 (3) S0|interlock state=PTT_REQUESTED reason=AMP:KZX-2500 source=MIC tx_allowed=1 (4) C2|interlock`` ``ready`` ``1 (5) R2|0| (6) S0|interlock state=TRANSMITTING source=MIC tx_allowed=1 (7) S0|interlock state=READY reason=AMP:KZX-2500 tx_allowed=1

In this example, the device registers an interlock for itself (2) and the radio responds with the interlock number (2) which is #1. The user then presses the PTT causing status (3) to be emitted. The device recognizes that transmit is in progress and readies itself for transmit and then sends a ready to the radio (4). The radio responds that it received the ready (5) and switches to transmitting (6). The radio is now emitting power. The used then releases the PTT and the radio switches back to a ready state (7), but the device is in a not ready state.

Create a dynamic ethernet interlock that will be used by an external device. Once the interlock is created, it is assumed to be enabled and the radio will immediately be NOT READY as a result. The radio will only go into the READY state after a PTT and after the device sends an 'interlock ready' command. The interlock will always be cleared back to NOT READY after each PTT release

C[D]<seq_number>|interlock create type=<interlock_type> model=<device_model> serial=<device_serial> valid_antennas=<comma_separated_antenna_list>

<interlock_type>  = the type of device requesting the interlock (see table)
<device_model>  = the model number of the device requesting the interlock
<device_serial>  = the serial number of the device requesting the interlock
<comma_separated_antenna_list> = Antennas that this interlock should apply to (for amps something like valid_antennas=ANT1,ANT2)

Example:

C21|interlock create type=AMP model=KZX-2500 serial=1234-5678 valid_antennas=ANT1

The table below shows the currently supported type parameters to the create command:

See Response Format for details on the format of the response messages from the radio

Responses

Response Example:

R21|0|000000F4

Signal that the external device is now ready to receive RF. This is generally sent after the device received an interlock state=PTT_REQUESTED status message. Failure to send this message within the timeout period of the interlock (generally 500ms) will result in an error message indicating that the external device is preventing transmit from occurring. The error message will be displayed in SmartSDR to the user as a balloon message or sent to other clients using the Message Format in the TCP/IP command stream.

C[D]<seq_number>|interlock ready <interlock_id>
C[D]<seq_number>|interlock not_ready <interlock_id>

< interlock_id >  = the interlock ID received when the interlock was created

Example:

C24|interlock ready 000000F4
C24|interlock not_ready 000000F4

See Response Format for details on the format of the response messages from the radio

Responses

Response Example:

R24|0

Temporarily disable the interlock. After this command, the radio will no longer wait for input from the remote device before sending RF. A typical use case would be to issue the disable command after an amplifier is placed into bypass

C[D]<seq_number>|interlock disable <interlock_id>

< interlock_id >  = the interlock ID received when the interlock was created

Example:

C25|interlock disable 000000F4

See Response Format for details on the format of the response messages from the radio

Responses

Response Example:

R25|0

Reenable a disabled interlock. After this command, the radio will return to the state right after creation of the interlock. A typical use case would be placing an amplifier back online from a bypass state.

C[D]<seq_number>|interlock enable <interlock_id>

< interlock_id >  = the interlock ID received when the interlock was created

Example:

C29|interlock enable 000000F4

See Response Format for details on the format of the response messages from the radio

Responses

Response Example:

R29|0

Remove a previously created interlock from the system. A typical use case would be removing the interlock before disconnecting from the radio when the amplifier is shutdown, etc. Once this command is issued, no more communications with the radio regarding this interlock_id will be accepted

C[D]<seq_number>|interlock remove <interlock_id>

< interlock_id >  = the interlock ID received when the interlock was created

Example:

C30|interlock remove 000000F4

See Response Format for details on the format of the response messages from the radio

Responses

Response Example:

R30|0