Overview
Metis is an Objective-C API that provides the API to communicate through UDP with an HPSDR Metis device.
Metis includes two delegates. One to pass Digital Down Converter (DDC) streams from a Metis device, and the other to pass control parameter changes from the Metis device.
Tasks
Creating a Metis object
Board Info
Metis Connection
Network
Delegates for Receiving Data
I/Q Data Sampling
Bandscope Data
Fetching Digital Down Converter Data
Setting Digital Down Converter Parameters
Radio Parameters
- setNumberOfReceivers:
- numberOfReceivers
- radio:usePreamp:
- radio:enableAttenuator:
- radio:setInputAttenuator:
- radio:enableADCDither:
- radio:useRandomDither:
Frequency Parameters
- receiver:setMHzFrequency:
- frequencyForReceiver:
- cordicFrequencyForReceiver:
- useDuplex:
- setTransmitMHzFrequency:
- transmitFrequency
- useCommonMercuryFrequency:
Sending Data
Exciter (Hermes)
Transmit PA and Tuner (Apollo)
- enableApolloFilter:
- selectApolloFilter:
- enableApolloTuner:
- startApolloTuner
- stopApolloTuner
Transmit Filters (Alex)
- selectAlexAttenuator:
- selectAlexRxAntenna:
- enableAlexRxOutput:
- selectAlexTxRelay:
- disableAlexT_RRelay:
- selectAlexFilterManually:
- bypassAlexHPF:
- alexHPF:enable:
- alexLPF:enable:
- useLNAOnAlex:
Analog I/O
Digital I/O
Others
Instance Methods
alexHPF:enable:
Switch in an Alex (RF Filter) HPF. Filter is one of kAlexHPF1500kHz (0x10), kAlexHPF6500kHz (0x8), kAlexHPF9500kHz (0x4), kAlexHPF13000kHz (0x1) or kAlexHPF20000kHz (0x2).
- (void)alexHPF:(AlexHPF)filter enable:(Boolean)enable
Parameters
filter
0x1, 0x2, 0x4,
0x8 or 0x10,
enable
true to switch in
HPF.
alexLPF:enable:
Switch in an Alex (RF Filter) LPF. Filter is one of kAlexLPF6m (0x10), kAlexLPF10m (0x20), kAlexLPF15m (0x40), kAlexLPF20m (0x1), kAlexLPF40m (0x2), kAlexLPF80m (0x4) or kAlexLPF160m (0x8).
- (void)alexLPF:(AlexLPF)filter enable:(Boolean)enable
Parameters
filter
0x1, 0x2, 0x4,
0x8 or 0x10, 0x20 or 0x40,
enable
true to switch in
LPF.
bandscopeRunning
Returns if Metis is returning bandscope data.
- (Boolean)bandscopeRunning
Return Value
True if Metis is sending a bandscope stream.
bypassAlexHPF:
Bypass all HPF in Alex (RF Filter).
- (void)bypassAlexHPF:(Boolean)bypass
Parameters
bypass
true to bypass
all HPF.
close
Close the UDP socket to the Metis device.
- (void)close
controlDelegate
Returns the control delegate. The control delegate is the object that receives delegate calls whenever parameters in hardware changes.
- (id)controlDelegate
Return Value
The control delegate. Returns nil if no control delegate has been set.
cordicFrequencyForReceiver:
Returns the true frequency in MHz for the specified receiver.
The -receiver:setMHzFrequency: method sends a frequency with a resolution of 1 Hz to the hardware. This number is converted into a large integer that is used by the Cordic process to iteratively generate the internal quadrature numerical oscillator in the Mercury/Hermes/Angelia firmware. Because of this, the resultant sine and cosine frequencies are not precisely rounded to 1 Hz resolution.
Older firmware simply truncated the frequencies with up to 28 milliHertz of error. A bug caused Hermes firmware versions v2.5 and v2.6 to produced errors of up to ±500 millHertz. Current (v2.7 onwards for Hermes) firmware produces ±14 milliHertz error.
The -cordicFrequencyForReceiver: is similar to the -frequencyForReceiver: method, but instead of returning the most recent frequency that was requested, it returns the actual frequency that is computed by the Cordic process. You can use this method if you need a more precise frequency.
- (double)cordicFrequencyForReceiver:(unsigned int)receiver
Parameters
receiver
index of the
receiver.
Return Value
The frequency in MHz.
dataDelegate
Returns the data delegate. The data delegate is the object that receives the DDC and microphone sample from Metis.
- (id)dataDelegate
Return Value
The data delegate. Returns nil if no data delegate has been set.
DB9OutputPin:setState:
Set state of DB9 open drain output pins 1,2 (enable=ON) and 3.3v TTL output pins 3,4 (enable =ON).
- (void)DB9OutputPin:(unsigned int)pin setState:(Boolean)enable
Parameters
pin
pin 1, 2, 3 or
4,
enable
state of open
collector bit.
disableAlexT_RRelay:
Disable Alex T/R relay.
- (void)disableAlexT_RRelay:(Boolean)disable
Parameters
disable
true to
disable.
enableAlexRxOutput:
Enable Alex Rx antenna out.
- (void)selectAlexRxOutput:(Boolean)enable
Parameters
enable
true to
enable.
enableApolloFilter:
Enable Apollo (15W Power Amplifier) filter.
- (void)enableApolloFilter:(Boolean)filter
Parameters
filter
true, to turn on
Apollo filters.
enableApolloTuner:
Enable Tuner in Apollo (15W Power Amplifier).
- (void)enableApolloTuner:(Boolean)tuner
Parameters
tuner
true, to turn on
Apollo tuner.
enableMicBoost:
Enable 20 dB microphone preamp.
- (void)enableMicBoost:(Boolean)boost
Parameters
boost
true, to turn on
20 dB microphone preamp.
enableVNAMode:
Enable VNA Mode.
- (void)enableVNAMode:(Boolean)enable
Parameters
enable
true, to to
enable VNA Mode.
frequencyForReceiver:
Returns the frequency in MHz for the specified receiver.
- (double)frequencyForReceiver:(unsigned int)receiver
Parameters
receiver
index of the
receiver.
Return Value
The frequency in MHz.
hostAddresses
Returns a pointer to a structure that contains the computer's IP address, its MAC address and its port number.
- (SocketAddresses*)hostAddresses
Return Value
A pointer to the SocketAddresses for the computer.
SocketAddressses is in the form
typedef struct {
in_addr_t
ip ;
unsigned char MAC[6] ;
int port ;
}
SocketAddresses ;unsigned char MAC[6] ;
int port ;
hostPort
The Metis Framework maintains separate sockets for use during Discovery, Programming and the rest of the packets (data, command and control).
hostPort returns the port number that is used by the latter operations. Although not documented in the HPSDR documentation, the Discovery and Programming packets must use the same port number. That port is the number that is returned by calling hostAddresses.
- (int)hostPort
Return Value
The port that is used for data, command and control.
init
This is the normal way of initializing a Metis object. This method calls NetworkInterfaces to find all networks (e.g., "en0", "en1", etc) and then asks MetisDiscovery to find a Metis device on each of the interfaces. init returns the first Metis device that is found.
- (id)init
Return Value
An initialized Metis object that is used to communicate with a Metis device. Returns nil if no Metis object is found on the networks.
initOnNetwork:
Same as -init, but only search for Metis device on one network. Example of usage: -initOnNetwork:"en1"
- (id)initOnNetwork:(char*)network
Parameters
network
the name of a
network, e.g., "en0", "en1", "fw0".
Return Value
An initialized Metis object that is used to communicate with a Metis device. Returns nil if no Metis object is found on the given network.
initWithAddress:
This API is useful when there are multiple Metis devices on the network. It works like the -init method above, but filters out devices that do not have the requested MAC address.
- (id)initWithAddress:(unsigned char*)MACaddress
Parameters
macAddress
MAC address of
the Metis device, in the form of an unsigned char array
with six octets
Return Value
An initialized Metis object that is used to communicate with a Metis device. Returns nil if no Metis device with the MAC address is found on the networks.
initWithDiscoveryMessage:metisAddress:interface:
This API is reserved for use by MetisDiscovery.
- (id)initWithDiscoveryMessage:(unsigned char*)msg metisAddress:(in_addr_t)ipAddress interface(NetworkInterface*)interface
Parameters
msg
the message
string that is returned by the Metis device in response
to a discovery request,
ipAddress
IP address of the
Metis device,
interface
Return Value
An initialized Metis object that is used to communicate with a Metis device. Returns nil if no Metis device is found on the interface.
isOpen
Returns if a socket is opened to the Metis device.
- (Boolean)isOpen
Return Value
The UDP socket if there is an open port to the Metis device, otherwise returns 0.
kHzSamplingRate
Returns the sampling rate in kHz. The return value is one of the following: 48, 96, 192 or 384.
- (int)kHzSamplingRate
Return Value
The sampling rate in kHz.
metisAddresses
Returns a pointer to a structure that contains the Metis device's IP address, its MAC address and its port number. The Metis device's port is always 1024.
- (SocketAddresses*)metisAddresses
Return Value
A pointer to the SocketAddresses for the Metis device
SocketAddresses is in the form
typedef struct {
in_addr_t
ip ;
unsigned char MAC[6] ;
int port ;
}
SocketAddresses ;unsigned char MAC[6] ;
int port ;
metisData
The Digital Down Converter output is normally passed to the data delegate with the metis:newData: callback as a MetisData structure. The structure can also be fetched by using the metisData method.
- (MetisData*)metisData
Return Value
The MetisData structure.
metisDataSize:
Returns the size of the ring buffer that is used to buffer the DDC data.
- (long)metisDataSize
Return Value
The number of samples of the ring buffer.
metisType
Returns the Metis board type. 0 = Metis, 1 = Hermes, 2 = Griffin, 4 = Angelia.
- (int)metisType
Return Value
The board type that Metis is implemented on.
networkInterface
Returns the NetworkInterface structure. The structure includes the host IP address and the network (e.g., "en0") that the connection is made to the Metis device.
- (MetisData*)metisData
Return Value
The MetisData structure.
numberOfReceivers
Returns the number of active receivers. This determines the number of receiver streams that are interleaved into metisData.
- (int)numberOfReceivers
Return Value
The number of active receivers.
open
Create a UDP socket to the Metis device.
- (int)open
Return Value
The UDP socket.
openWithHeartbeat
Create a UDP socket to the Metis device and periodically send it a dummy command message.
- (int)openWithHeartbeat:(float)period
Parameters
period
heartbeat period
in seconds.
Return Value
The UDP socket.
openCollectorBit:setState:
Set state of open collector output bits 0...6.
- (void)openCollectorBit:(unsigned int)bit setState:(Boolean)enable
Parameters
bit
bit 0 through
6,
enable
state of open
collector bit.
quietState
Returns the quiet state (see setQuietState).
- (Boolean)quietState
Return Value
True if Metis is set to quiet state.
radio:enableADCDither:
Turns the LTC-2208 ADC dithering on or off.
- (void)radio:(unsigned int)radio enableADCDither:(Boolean)dither
Parameters
radio
the index of the
radio (base 1),
dither
true, to turn
dithering on.
radio:enableAttenuator:
Turns the attenuators on or off. This must be disabled for Hermes to disable its preamp.
- (void)radio:(unsigned int)radio enableAttenuator:(Boolean)attenuatorOn
Parameters
radio
the index of the
radio (base 1),
attenuatorOn
true, to turn
attenuators on.
radio:setInputAttenuator:
Sets the Hermes attenuator (0 to 31 dB).
- (void)radio:(unsigned int)radio setInputAttenuator:(unsigned int)attenuation
Parameters
radio
the index of the
radio (base 1),
attenuation
attenuation in 1
dB steps.
radio:usePreamp:
Turns the preamp of a radio on or off. (see radio:enableAttenuator:)
- (void)radio:(unsigned int)radio usePreamp:(Boolean)preampOn
Parameters
radio
the index of the
radio (base 1),
preampOn
true, to turn
preamp on.
radio:useRandomDither:
Turns the LTC-2208 ADC dithering random mode on or off.
- (void)radio:(unsigned int)radio useRandomDither:(Boolean)random
Parameters
radio
the index of the
radio (base 1),
random
true, to use
random dithering.
receiver:setMHzFrequency:
Sets the frequency for the specified receiver.
- (Boolean)receiver:(unsigned int)receiver setMHzFrequency:(double)frequency
Parameters
receiver
the index of the
receiver,
frequency
frequency in
MHz.
Return Value
True, if successful.
resendControls
Control on the Metis board are usually sent to the control delegate when the Metis object detects a change. This message causes all control delegate callbacks to be called.
- (void)resendControls
running
Returns if Metis is returning I/Q data.
- (Boolean)running
Return Value
True if Metis is sending bandscope stream.
selectAlexAttenuator:
Select attenuator on Alex (RF filter). attenuation is kAlexAttenuation0dB (0), kAlexAttenuation10dB (1), kAlexAttenuation20dB (2) or kAlexAttenuation30dB (3).
- (void)selectAlexAttenuator:(AlexAttenuator)attenuation
Parameters
attenuation
amount of
attenuation (0, 10 dB, 20 dB or 30 dB).
selectAlexFilterManually:
Manually select HPF/LPF in Alex (RF Filter).
- (void)selectAlexFilterManually:(Boolean)enable
Parameters
enable
true to select
manually.
selectAlexRxAntenna:
Select attenuator on Alex (RF filter). antenna is kAlexRxAntennaNone (0), kAlexRxAntenna1 (1), kAlexRxAntenna2 (2) or kAlexRxAntennaXVTR (3).
- (void)selectAlexRxAntenna:(AlexRxAntenna)antenna
Parameters
antenna
antenna selection
(0, 1, 2 or 3).
selectAlexTxRelay:
Select Alex transmit relay. antenna is kAlexTxRelay1 (0), kAlexTxRelay2 (1), kAlexTxRelay3 (2).
- (void)selectAlexTxRelay:(AlexTxRelay)relay
Parameters
relay
antenna selection
(0, 1, 2).
selectApolloFilter:
Select filter on Apollo (15W Power Amplifier) if true, filters on Alex (RF Filters) if false.
- (void)selectApolloFilter:(Boolean)apollo
Parameters
apollo
use filters on
Apollo if true, filters on Alex if false.
sendIQ::audio::samples:ptt:
Send the 48 ksps I/Q data stream and line output audio data stream to Metis. Each Metis UDP packet carries two HPSDR frames. Each HPSDR frame has 63 I/Q and audio samples.
The Metis framework accumulates the data until two HPSDR frames worth of data before sending it. If the sendIQ::audio::samples:ptt: call receives more than 63 samples, it can send multiple UDP packets in a group.
If the data pointer of a stream is nil, it is assumed that the stream consists of zero bytes. The right audio channel is set to nil to mute the right headphones output. The I and Q pointers can be set to nil when not transmitting.
The ptt state is used to assert the MOX bit of an HPSDR frame. If the ptt state changes before an HPSDR frame is generated, the most recent ptt state is sent with the HPSDR frame.
For minimal latency between the IQ samples and ptt, call sendIQ with 63 (not 64) sample blocks.
- (SendStatus)sendIQ:(float*)iData:(float*)qData audio:(float*)left:right samples:(int)samples ptt:(Boolean)ptt
Parameters
iData
in phase
component of the 48 ksps transmit stream,
qData
quadrature
component of the 48 ksps transmit stream,
left
left channel of
the 48 ksps headphones output,
right
right channel of
the 48 ksps headphones output,
samples
number of 48 ksps
samples,
ptt
ptt state for
this block of data.
Return Value
SendStatus structure (see Metis.h).
setControlDelegate:
Set the control delegate. The control delegate is the delegate that receives delegate calls whenever parameters in hardware changes.
The delegate should implement the MetisControlDelegate protocol.
- (void)setControlDelegate:(id)object
Parameters
object
the object that
receives the delegate calls.
setDataDelegate:
Set the data delegate. The data delegate is the delegate that receives the I/Q data samples from Metis.
The delegate should implement the MetisDataDelegate protocol.
- (void)setDataDelegate:(id)object
Parameters
object
the object that
receives the delegate calls.
setDriveLevel:
Set the Hermes/Pennylane drive level (0-255).
- (void)setDriveLevel:(unsigned int)drive
Parameters
driveLevel
drive level,
between 0 and 255.
setkHzSamplingRate:
Sets the sampling rate. The rate should be one of the following integers: 48, 96, 192 or 384.
- (void)setkHzSamplingRate:(int)rate
Parameters
rate
the sampling rate
in kHz.
setLineInGain:
Set the line input gain (0-31).
- (void)setLineInGain:(unsigned int)gain
Parameters
gain
gain between 0
and 31.
setNumberOfReceivers:
Sets the number of active receivers. This determines the number of receiver streams that are interleaved into metisData.
Since the number of receivers is set in the firmware, the connection has to be open (see -isOpen) before calling setNumberOfReceivers.
- (void)setNumberOfReceivers:(unsigned int)receivers
Parameters
receivers
the number of
active receivers.
setMetisDataSize:
Sets the size of the ring buffer that is used to buffer the DDC data. The default size is 131,072 samples.
This must be called while Metis is not in running state.
- (Boolean)setMetisDataSize:(long)samples
Parameters
samples
the number of
samples.
Return Value
True if the size is set command succeeds.
setQuietState:
Allows all control and command packets to the firmware (except for programming packets) to be turned off. This method before calling any Programmer methods.
- (void)setQuietState:(Boolean)state
Parameters
state
setTransmitMHzFrequency:
Sets the frequency for the transmitter.
- (Boolean)setMHzFrequency:(double)frequency
Parameters
frequency
frequency in
MHz.
Return Value
True, if successful.
start
Start the DDC I/Q steam from Metis.
- (Boolean)start
Return Value
True if the start command succeeds. The device has to be first open.
startApolloTuner
Start tuner on Apollo (15W PA).
- (void)startApolloTuner
startBandscope
Starts bandscope stream from Metis.
- (Boolean)startBandscope
Return Value
True if the startBandscope command succeeds. The device has to be first open.
stop
Stop the I/Q steam from Metis.
- (Boolean)stop
Return Value
True if the stop command succeeds.
stopBandscope
Stop the bandscope steam from Metis.
- (Boolean)stopBandscope
Return Value
True if the stopBandscope command succeeds.
stopApolloTuner
Stop tuner on Apollo (15W PA).
- (void)stopApolloTuner
transmitFrequency
Returns the transmit frequency in MHz .
- (double)transmitFrequency
Return Value
The frequency in MHz.
udpSocket
Returns the UDP socket to the Metis device.
- (int)udpSocket
Return Value
The UDP socket.
useClassEModulation:
Enable for Class E modulation. Disable for all other modes.
- (void)useClassEModulation:(Boolean)enable
Parameters
enable
true, to turn on
Class E modulation
useCommonMercuryFrequency:
Use the same frequency for all Mercury boards.
- (void)useCommonMercuryFrequency:(Boolean)common
Parameters
common
true, if all
Mercury boards shares the same frequency.
useDuplex:
When duplex mode is not set, receiver 1 takes its NCO frequency from the transmit NCO. When duplex is set, receiver 1 and transmitter have independent frequencies.
- (void)useDuplex:(Boolean)duplex
Parameters
duplex
set
to true to use independent
transmit and receiver 1 frequency.
useLineIn:
Select between line input and microphone input.
- (void)useLineIn:(Boolean)lineInput
Parameters
lineInput
true, to use line
input, false to use microphone input.
useLNAOnAlex:
Use LNA on Alex (RF Filter).
- (void)useLNAOnAlex:(Boolean)enable
Parameters
enable
true, to use LNA
on Alex.
useTimeStamp:
Turns on 1 pulse per second on least significant bit of microphone channel.
- (void)useTimeStamp:(Boolean)enable
Parameters
enable
true, to turn on
time stamp pulse.
versionNumber
Returns the integer representation of the firmware version number. By convention, the HPSDR version numbers are in the form of d.dd. The returned integer is divided by 10 to get this firmware version. E.g., versionNumber of 23 corresponds to a firmware version 2.3.
- (int)versionNumber
Return Value
The integer representation of the firmware version number.
write:length:
This API is reserved for use by sendMetisPacket to send a buffer of bytes to the UDP socket to Metis. The method does nothing when Metis is set to quiet state (see setQuietState).
- (Boolean)write:(unsigned char*)bytes length:(int)length
Parameters
bytes
the bytes to be
sent,
length
the number of
bytes.
Return Value
True if successfully sent.
writeAlways:length:
This is the same as -write:length: mothod above, but it is not inhibited by the quiet state (see setQuietState).
- (Boolean)writeAlways:(unsigned char*)bytes length:(int)length
Parameters
bytes
the bytes to be
sent,
length
the number of
bytes.
Return Value
True if successfully sent.