The class that represents the Radio as a state machine. More...

#include <PhyUtils.h>

Collaboration diagram for Radio:

Public Types
enum	RadioState { RX = 0, TX, SLEEP, SWITCHING, NUM_RADIO_STATES }
	The state of the radio of the nic. More...
Public Member Functions
virtual	~Radio ()
	Destructor for the Radio class.
virtual simtime_t	switchTo (int newState, simtime_t now)
	A function called by the Physical Layer to start the switching process to a new RadioState.
virtual void	setSwitchTime (int from, int to, simtime_t time)
	function called by PhyLayer in order to make an entry in the switch times matrix, i.e. set the time for switching from one state to another
virtual int	getCurrentState () const
	Returns the state the Radio is currently in.
virtual void	endSwitch (simtime_t now)
	called by PhyLayer when duration-time for the current switching process is up
virtual RadioStateAnalogueModel *	getAnalogueModel ()
	Returns a pointer to the RadioStateAnalogueModel.
virtual void	cleanAnalogueModelUntil (simtime_t t)
	discards information in the RadioStateAnalogueModel before given time-point
void	setTrackingModeTo (bool b)
	sets tracking mode
void	setCurrentChannel (int newChannel)
	Changes the current channel of the radio.
int	getCurrentChannel ()
	Returns the channel the radio is currently set to.
Static Public Member Functions
static Radio *	createNewRadio (bool recordStats=false, int initialState=RX, double minAtt=1.0, double maxAtt=0.0, int currentChannel=0, int nbChannels=1)
	Creates a new instance of this class.
Protected Member Functions
	Radio (int numRadioStates, bool recordStats, int initialState=RX, double minAtt=1.0, double maxAtt=0.0, int currentChannel=0, int nbChannels=1)
	Intern constructor to initialize the radio.
virtual void	makeRSAMEntry (simtime_t time, int state)
	responsible for making entries to the RSAM
virtual double	mapStateToAtt (int state)
	maps RadioState to attenuation, the Radios receiving characteristic
Protected Attributes
cOutVector	radioStates
	Output vector for radio states.
cOutVector	radioChannels
	Output vector for radio channels.
int	state
	The current state the radio is in.
int	nextState
	The state the radio is currently switching to.
const int	numRadioStates
	The number of radio states this Radio can be in.
simtime_t **	swTimes
	Array for storing switch-times between states.
const double	minAtt
	Constant to store the minimum attenuation for a Radio instance.
const double	maxAtt
	Constant to store the maximum attenuation for a Radio instance.
RadioStateAnalogueModel	rsam
	The corresponding RadioStateAnalogueModel.
int	currentChannel
	Currently selected channel (varies between 0 and nbChannels-1).
int	nbChannels
	Number of available channels.

Detailed Description

The class that represents the Radio as a state machine.

The Radio creates and updates its corresponding RadioStateAnalogueModel, that is a filter representing the radios attenuation to a Signal depending on the RadioState over time.

For this basic version we assume a minimal attenuation when the Radio is in state RX, and a maximum attenuation otherwise.

A state-machine-diagram for Radio, RadioStateAnalogueModel and ChannelInfo showing how they work together under control of BasePhyLayer as well as some documentation on how RadioStateAnalogueModel works is available in phyLayer - physical layer modules.

Definition at line 190 of file PhyUtils.h.

Member Enumeration Documentation

enum Radio::RadioState

The state of the radio of the nic.

Enumerator:

RX	receiving state
TX	transmitting state
SLEEP	sleeping
SWITCHING	switching between two states
NUM_RADIO_STATES	No real radio state just a counter constant for the amount of states. Sub-classing Radios which want to add more states can add their own states in their own enum beginning at the value of NUM_RADIO_STATES. They should also remember to update the "numRadioStates" member accordingly. See also: RadioUWBIR for an example.

Definition at line 196 of file PhyUtils.h.

                  {
    RX = 0,
    TX,
    SLEEP,
    SWITCHING,

    NUM_RADIO_STATES
  };

Constructor & Destructor Documentation

Radio::Radio	(	int	numRadioStates,
		bool	recordStats,
		int	initialState = `RX`,
		double	minAtt = `1.0`,
		double	maxAtt = `0.0`,
		int	currentChannel = `0`,
		int	nbChannels = `1`
	)			`[protected]`

Intern constructor to initialize the radio.

By defining no default constructor we assure that sub classing radios have to explicitly call this constructor which assures they pass the correct number of radio states.

The protected constructor + factory method solution assures that while sub-classing Radios HAVE to explicitly pass their correct amount of radio states to this constructor, the user (creator) of the Radio doesn't has to pass it or even know about it (which wouldn't be possible with a public constructor). Therefore sub classing Radios which could be sub-classed further should also do it this way.

Definition at line 84 of file PhyUtils.cc.

References radioChannels, radioStates, and swTimes.

Referenced by createNewRadio().

                                          :
  state(initialState), nextState(initialState),
  numRadioStates(numRadioStates),
  minAtt(minAtt), maxAtt(maxAtt),
  rsam(mapStateToAtt(initialState)),
  currentChannel(currentChannel), nbChannels(nbChannels)
{
  assert(nbChannels > 0);
  assert(currentChannel > -1);
  assert(currentChannel < nbChannels);

  radioStates.setName("RadioState");
  radioStates.setEnabled(recordStats);
  radioStates.record(initialState);
  radioChannels.setName("RadioChannel");
  radioChannels.setEnabled(recordStats);
  radioChannels.record(currentChannel);

  // allocate memory for one dimension
  swTimes = new simtime_t* [numRadioStates];

  // go through the first dimension and
  for (int i = 0; i < numRadioStates; i++)
  {
    // allocate memory for the second dimension
    swTimes[i] = new simtime_t[numRadioStates];
  }

  // initialize all matrix entries to 0.0
  for (int i = 0; i < numRadioStates; i++)
  {
    for (int j = 0; j < numRadioStates; j++)
    {
      swTimes[i][j] = 0;
    }
  }
}

Member Function Documentation

static Radio* Radio::createNewRadio	(	bool	recordStats = `false`,
		int	initialState = `RX`,
		double	minAtt = `1.0`,
		double	maxAtt = `0.0`,
		int	currentChannel = `0`,
		int	nbChannels = `1`
	)			`[inline, static]`

Creates a new instance of this class.

Since Radio hasn't a public constructor this is the only way to create an instance of this class.

This method assures that the radio is initialized with the correct number of radio states. Sub classing Radios should also define a factory method like this instead of an public constructor.

Definition at line 266 of file PhyUtils.h.

References currentChannel, maxAtt, minAtt, nbChannels, NUM_RADIO_STATES, and Radio().

Referenced by BasePhyLayer::initializeRadio().

  {
    return new Radio(NUM_RADIO_STATES,
             recordStats,
             initialState,
             minAtt, maxAtt,
             currentChannel, nbChannels);
  }

void Radio::endSwitch ( simtime_t now ) [virtual]

called by PhyLayer when duration-time for the current switching process is up

Radio checks whether it is in switching state (pre-condition) and switches to the target state

The actual simtime must be passed, to create properly RSAMEntry

Definition at line 185 of file PhyUtils.cc.

References makeRSAMEntry(), nextState, radioStates, state, and SWITCHING.

Referenced by BasePhyLayer::finishRadioSwitching(), RadioUWBIR::finishReceivingFrame(), and RadioUWBIR::startReceivingFrame().

{
  // make sure we are currently switching
  assert(state == SWITCHING);

  // set the current state finally to the next state
  state = nextState;
  radioStates.record(state);

  // make entry to RSAM
  makeRSAMEntry(now, state);

  return;
}

virtual RadioStateAnalogueModel* Radio::getAnalogueModel ( ) [inline, virtual]

Returns a pointer to the RadioStateAnalogueModel.

This method is intended to be used by the PhyLayer to obtain a pointer to the corresponding RSAM to this Radio

Definition at line 328 of file PhyUtils.h.

References rsam.

Referenced by PhyLayerUWBIR::getAnalogueModelFromName(), BasePhyLayer::getAnalogueModelFromName(), and BasePhyLayer::~BasePhyLayer().

                                                      {
    return (&rsam);
  }

int Radio::getCurrentChannel ( ) [inline]

Returns the channel the radio is currently set to.

Returns:: The current channel of the radio, between 0 and nbChannels-1.

Definition at line 364 of file PhyUtils.h.

References currentChannel.

Referenced by PhyLayerUWBIR::encapsMsg(), BasePhyLayer::encapsMsg(), BasePhyLayer::getCurrentRadioChannel(), PhyLayer::initializeDecider80211(), and PhyLayerBattery::initializeDecider80211Battery().

                          {
    return currentChannel;
  }

void Radio::setCurrentChannel ( int newChannel ) [inline]

Changes the current channel of the radio.

Parameters:

newChannel

The new channel to switch to, between 0 and nbChannels-1

Definition at line 353 of file PhyUtils.h.

References currentChannel, nbChannels, and radioChannels.

Referenced by BasePhyLayer::setCurrentRadioChannel().

                                         {
    assert(newChannel > -1);
    assert(newChannel < nbChannels);
    currentChannel = newChannel;
    radioChannels.record(currentChannel);
  }

simtime_t Radio::switchTo	(	int	newState,
		simtime_t	now
	)			`[virtual]`

A function called by the Physical Layer to start the switching process to a new RadioState.

Returns:: -1: Error code if the Radio is currently switching else: switching time from the current RadioState to the new RadioState

The actual simtime must be passed, to create properly RSAMEntry

Reimplemented in RadioUWBIR.

Definition at line 138 of file PhyUtils.cc.

References makeRSAMEntry(), nextState, numRadioStates, radioStates, state, SWITCHING, and swTimes.

Referenced by BasePhyLayer::setRadioState().

{
  // state to switch to must be in a valid range, i.e. 0 <= newState < numRadioStates
  assert(0 <= newState && newState < numRadioStates);

  // state to switch to must not be SWITCHING
  assert(newState != SWITCHING);


  // return error value if newState is the same as the current state
  // if (newState == state) return -1;

  // return error value if Radio is currently switching
  if (state == SWITCHING) return -1;


  /* REGULAR CASE */


  // set the nextState to the newState and the current state to SWITCHING
  nextState = newState;
  int lastState = state;
  state = SWITCHING;
  radioStates.record(state);

  // make entry to RSAM
  makeRSAMEntry(now, state);

  // return matching entry from the switch times matrix
  return swTimes[lastState][nextState];
}