|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface AntennaElectronics
The electronics system of a radio antenna.
The main job of the antenna electronics is to produce a collection
of digital signals
. Those signals may then
be used by down stream electronics, such as the correlator of
an interferometer. These electronics can be expected to configure
themselves for a particular receiver band, or to produce
a given set of outputs. In this context "configure" will usually
mean the setting of switches and the tuning of local oscillators.
Getting an Instance
Clients are discouraged from creating new instances of this type by
using the constructors of implementing classes. The preferred way to get
an instance of this type is to use the
makeElectronics
method of the
TelescopeType
class.
Getting Output Signals
Three methods return a collection of digital signals:
execute()
, getSignals()
, and getSignalPairs()
.
The getSignalXxx methods return the signals produced by
the most recent call to the execute
method. Calling either of the
getSignalXxx methods does not
rerun this device. If this device has never been run, the
returned collection of signals will be empty. The signals returned
by the getSignalXxx methods are copies of the true outputs,
so changes made to them by clients will not be reflected in subsequent calls
to those methods.
The execute
method, on the other hand, runs this device based
on its current configuration, remembers the outputs produced
(so that the getSignalXxx methods can quickly retrieve them),
and returns copies of those output signals.
The normal sequence is for a client to acquire the
electronics for their telescope of choice, configure those
electronics, and then execute them. Concrete implementations of
this interface, though, are expected to be created with
a default configuration that could be executed immediately.
Execution without client-specified configuration instructions, however,
will not generally be useful.
Configuring the Electronics Using Internal Intelligence
There are two main categories of configuration methods: those that configure
the electronics immediately, and those that give directions that the
electronics may use when one of the immediate configuration methods
is called. Let us cover the latter first.
The two submitTuningPlan
methods provide this device with
instructions that it can use when one of the configureXxx
methods
is called. They provide, on a receiver-by-receiver basis, a
set of frequency tunings for the local oscillators that feed
this device. Concrete implementations are expected to
come with a default set of tuning instructions for each of
their receivers.
Of the immediate configuration methods, the
configureToProduce(Collection)
method
is the most generic, as it does not rely on even knowing the
receivers that feed these electronics. It is expected that implementing
classes will use the requested output signals to choose one or more
receivers, set internal switches, and tune local oscillators according
to either default plans or plans submitted by clients.
The configureFor(ReceiverBand)
methods ask clients to specify
the receiver band(s) they want to use, but do not expect them to know
anything else about the electronics.
Configuring the Electronics Manually
Knowledgable clients may use the
configureFrom(AntennaElectronicsConfiguration)
method to set
switches, tune local oscillators, and select the number of bits for the
digital samplers directly. This method gives clients the most control
over the internal settings of these electronics.
Tuning the Local Oscillators Manually
In addition to the configuration methods mentioned above, clients
may fetch the local oscillators and tune them independently.
The LOs returned by this method are the LOs referenced internally
by this device, so changes made to them by clients will be
reflected herein. Note that the LOs can also be tuned somewhat
directly by using the configureFrom(AntennaElectronicsConfiguration)
method. Fetching the local oscillators directly and then tuning them
can be useful for those clients who want to first take advantage
of the intelligence used in the other configureXxx for setting
switches, but tweak the LO setting themselves.
Interaction of the Configuration Methods
In general, the configuration method called just prior to the execution
of this device dominates. For example, if a client were to call
configureToProduce
and then fetch and tune the local oscillators,
some or all of the work done by configureToProduce
would be
overridden. Tuning the LOs manually after a call to one of the
configureFor
methods could make sense, though, as one of the main
jobs of the configureFor
methods is to ensure that this device
takes its input from a given receiver(s). Clients may wish to
then tweak the LO settings determined by this device.
This is most useful for testing and debugging. In general, clients
will not need to tweak the LO settings themselves.
Version Info:
$Revision: 1699 $ |
$Date: 2008-11-07 13:27:05 -0700 (Fri, 07 Nov 2008) $ |
$Author: dharland $ (last person to modify) |
Method Summary | |
---|---|
void |
addExecutionListener(ActionListener newListener)
Registers a new listener that will be notified whenever the execute() method is called. |
AntennaElectronics |
clone()
|
boolean |
configureFor(ReceiverBand band)
Configures these electronics to work with the given receiver band. |
boolean |
configureFor(Set<ReceiverBand> bands)
Configures these electronics to work with the given set of receiver bands. |
boolean |
configureFrom(AntennaElectronicsConfiguration configuration)
Configures these electronics by setting switches and tuning local oscillators according to the instructions in the given configuration. |
boolean |
configureToProduce(Collection<DigitalSignal> signals)
Attempts to configure these electronics to produce the given signals. |
Collection<DigitalSignal> |
execute()
Runs these electronics and returns a collection of the signals produced. |
SortedSet<AntennaFrontEnd> |
getActiveFrontEnds()
Returns front end(s) for which these electronics were most recently configured. |
SortedSet<ReceiverBand> |
getActiveReceivers()
Returns receiver(s) for which these electronics were most recently configured. |
AntennaElectronicsConfiguration |
getConfiguration()
Returns a configuration that contains the current settings of the switches and local oscillators of these electronics. |
List<String> |
getConfigurationProblems()
Returns a list of problems associated with the most recent attempt to configure these electronics. |
SortedMap<String,Digitizer> |
getDigitizers()
Returns the digitizers used in these electronics. |
SortedMap<String,LocalOscillator> |
getLocalOscillators()
Returns the local oscillators used in these electronics. |
List<List<DigitalSignal>> |
getSignalPairs()
Returns the digital signals produced by the most recent execution of these electronics,
organized into pairs. |
Collection<DigitalSignal> |
getSignals()
Returns the digital signals produced by the most recent execution of these electronics. |
SortedMap<String,SignalSwitch> |
getSwitches()
Returns those switches in these electronics that may be set externally. |
SortedMap<String,SignalTransferSwitch> |
getTransferSwitches()
Returns those transfer switches in these electronics that may be set externally. |
void |
removeExecutionListener(ActionListener formerListener)
Removes formerListener from this electronics' list of
execution listeners. |
void |
submitTuningPlan(Map<ReceiverBand,Map<String,Frequency>> plans)
Allows clients to tell this electronics how to tune its oscillators for a set of receiver bands. |
void |
submitTuningPlan(ReceiverBand band,
Map<String,Frequency> plan)
Allows clients to tell this electronics how to tune its oscillators for a particular receiver band. |
Method Detail |
---|
Collection<DigitalSignal> execute()
Collection<DigitalSignal> getSignals()
execution
of these electronics.
The returned collection will never be null, but could be
empty. None of the elements contained in the returned collection
will be null.
List<List<DigitalSignal>> getSignalPairs()
execution
of these electronics,
organized into pairs.
The returned collection will never be null, but could be empty. Each element of the collection is a list of size two. Normally both elements of the inner lists are non-null. However, it is possible for one, but not both, of the elements of the inner lists to be null. This occurs when a signal has no partner.
void addExecutionListener(ActionListener newListener)
execute()
method is called. Listeners will be notified
after the execute method has already performed its
work and may not be notified at all if there is an unexpected failure.
newListener
- an object that will be notified upon successful completion of the
execute()
method.void removeExecutionListener(ActionListener formerListener)
formerListener
from this electronics' list of
execution listeners. If formerListener
is not currently
a registered execution listener, this method does nothing.
formerListener
- an object that no longer wishes to be notified upon successful
completion of the execute()
method.boolean configureFor(ReceiverBand band)
Once these electronics have been configured, the
SignalProcessor.execute()
may be run to produce signals
from this band.
band
- the receiver band, or frequency range, for which these electronics
should be configured.
getConfigurationProblems()
.boolean configureFor(Set<ReceiverBand> bands)
getConfigurationProblems()
.
bands
- the receiver bands, or frequency ranges, for which these electronics
should be configured.
getConfigurationProblems()
.boolean configureToProduce(Collection<DigitalSignal> signals)
signals
- the digital output for which these electronics should be configured.
getConfigurationProblems()
.boolean configureFrom(AntennaElectronicsConfiguration configuration)
configuration
- a container of switch settings and local oscillator tunings that
should be used to configure these electronics.
getConfigurationProblems()
.AntennaElectronicsConfiguration getConfiguration()
SortedMap<String,LocalOscillator> getLocalOscillators()
This method is normally used for discovering the frequencies to which the internal oscillators are tuned. This method also gives clients the opportunity to change the LO tunings. Clients must have some knowledge of the implementing class in order to do this in a meaningful way. Thus, this method is not generally used for manipulating the tunings.
SortedMap<String,SignalSwitch> getSwitches()
This method is normally used for discovering the input and output poles to which the internal switches are set. This method also gives clients the opportunity to change the switch settings. Clients must have some knowledge of the implementing class in order to do this in a meaningful way. Thus, this method is not generally used for manipulating the switches.
SortedMap<String,SignalTransferSwitch> getTransferSwitches()
This method is normally used for discovering the orientation to which the internal switches are set. This method also gives clients the opportunity to change the orientations. Clients must have some knowledge of the implementing class in order to do this in a meaningful way. Thus, this method is not generally used for manipulating the switches.
SortedMap<String,Digitizer> getDigitizers()
This method is normally used for discovering the bit-per-sample values that the digitizers are set to produce. This method also gives clients the opportunity to change those values. Clients must have some knowledge of the implementing class in order to do this in a meaningful way. Thus, this method is not generally used for manipulating the valuess.
void submitTuningPlan(Map<ReceiverBand,Map<String,Frequency>> plans)
It is expected that implementing classes will already know how to configure themselves, including tuning their LOs, for a given band. However, this method exists for those clients who have enough knowledge to meaningfully change that plan. The submitted map need not contain a plan for every receiver band handled by this electronics.
Note that a tuning plan as specified may be unimplementable. This can happen when a specified frequency is too high or too low for a given LO, or when a specified frequency is in between the tunable frequencies of a discretely tunable LO. In both these situations the LOs will be tuned as closely as they can to the plan.
plans
- a set of LO tuning plans for particular receiver bands. The
map that is the value object of the outer map has a key whose
value is the name of a contained LO. The value object of this
inner map is the frequency to which that LO should be tuned.void submitTuningPlan(ReceiverBand band, Map<String,Frequency> plan)
See submitTuningPlan(Map)
for more information concerning
the use of this method.
band
- the band for which the plan
applies.plan
- A map whose key is the name of local oscillator contained by this
electronics, and whose value is the frequency to which that LO
should be tuned.SortedSet<ReceiverBand> getActiveReceivers()
Note that the returned set is not held internally by this class, therefore
changes made to it will not be reflected herein. To change the active
receivers, use one of the configureFor
methods.
SortedSet<AntennaFrontEnd> getActiveFrontEnds()
Note that the returned set is not held internally by this class, therefore
changes made to it will not be reflected herein. To change the active
front ends, use one of the configureFor
methods.
getActiveReceivers()
List<String> getConfigurationProblems()
The returned list will never be null, but it will be empty if there were no problems with the latest configuration or if no attempt at configuration has ever been made. The returned list is not held internally by this object, so changes made to it will have no effect on this object.
AntennaElectronics clone()
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |