[Tinyos-beta-commits] CVS: tinyos-1.x/beta/teps/txt tep105.txt, 1.1, 1.2

Sun Jan 23 23:13:09 PST 2005

Update of /cvsroot/tinyos/tinyos-1.x/beta/teps/txt
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv27838

Modified Files:
	tep105.txt 
Log Message:
updates to the radio TEP to match the implementation and 
discussions

Index: tep105.txt
===================================================================
RCS file: /cvsroot/tinyos/tinyos-1.x/beta/teps/txt/tep105.txt,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** tep105.txt	18 Jan 2005 22:13:29 -0000	1.1
--- tep105.txt	24 Jan 2005 07:13:06 -0000	1.2
***************
*** 57,72 ****
         interrupts and timer capture events (general I/O)

! interface HPLCC2420 {
!   async command uint8_t cmd(uint8_t addr);
!   async command uint8_t write(uint8_t addr, uint16_t data);
!   async command uint16_t read(uint8_t addr);
! }
! 
! // a subset of the capture provided by the hardware
! interface HPLCC2420Capture {
!   async command result_t enableCapture(bool low_to_high);
!   async event result_t captured(uint16_t val);
!   async command result_t disable();
! }

--- 57,72 ----
         interrupts and timer capture events (general I/O)

! | interface HPLCC2420 {
! |   async command uint8_t cmd(uint8_t addr);
! |   async command uint8_t write(uint8_t addr, uint16_t data);
! |   async command uint16_t read(uint8_t addr);
! | }
! |
! | // a subset of the capture provided by the hardware
! | interface HPLCC2420Capture {
! |   async command result_t enableCapture(bool low_to_high);
! |   async event result_t captured(uint16_t val);
! |   async command result_t disable();
! | }

***************
*** 77,86 ****
         read/write 128-byte FIFO

! interface HPLCC2420FIFO {
!   async command cc2420_result_t readRXFIFO(uint8_t length, uint8_t *data);
!   async command cc2420_result_t writeTXFIFO(uint8_t length, uint8_t *data);
!   async event result_t RXFIFODone(uint8_t length, uint8_t *data, cc2420_result_t success);
!   async event result_t TXFIFODone(uint8_t length, uint8_t *data, cc2420_result_t success);
! }

    f. The HPL interfaces reside in the radio's "chips" directory while
--- 77,86 ----
         read/write 128-byte FIFO

! | interface HPLCC2420FIFO {
! |   async command cc2420_result_t readRXFIFO(uint8_t length, uint8_t *data);
! |   async command cc2420_result_t writeTXFIFO(uint8_t length, uint8_t *data);
! |   async event result_t RXFIFODone(uint8_t length, uint8_t *data, cc2420_result_t success);
! |   async event result_t TXFIFODone(uint8_t length, uint8_t *data, cc2420_result_t success);
! | }

    f. The HPL interfaces reside in the radio's "chips" directory while
***************
*** 119,130 ****
       listening.

! interface CSMAControl
! {
!   async command result_t enableCCA();
!   async command result_t disableCCA();
!   async command result_t enableAck();
!   async command result_t disableAck();
!   async command TOS_MsgPtr HaltTx();
! }

       The units of the CSMA Backoff are *SYMBOL PERIODS* of the radio.
--- 119,130 ----
       listening.

! | interface CSMAControl
! | {
! |   async command result_t enableCCA();
! |   async command result_t disableCCA();
! |   async command result_t enableAck();
! |   async command result_t disableAck();
! |   async command TOSMsg* HaltTx();
! | }

       The units of the CSMA Backoff are *SYMBOL PERIODS* of the radio.
***************
*** 132,140 ****
       normal time units.

! interface CSMABackoff
! {
!   async event int16_t initialBackoff(TOS_MsgPtr m);
!   async event int16_t congestionBackoff(TOS_MsgPtr m);
! }

       Low Power Listening provides additional challenges as the notation
--- 132,140 ----
       normal time units.

! | interface CSMABackoff
! | {
! |   async event int16_t initial(TOSMsg* m);
! |   async event int16_t congestion(TOSMsg* m);
! | }

       Low Power Listening provides additional challenges as the notation
***************
*** 145,157 ****
       option).  A proposal:

! interface LowPowerListening
! {
!   async command result_t SetMode(lpl_mode_t mode);
!   async command lpl_mode_t GetMode();
!   async command result_t SetListeningMode(lpl_mode_t mode);
!   async command lpl_mode_t GetListeningMode();
!   async command result_t SetTransmitMode(lpl_mode_t mode);
!   async command lpl_mode_t GetTransmitMode();
! }

       The lpl_mode_t values are mapped by the specific radio implementation
--- 145,157 ----
       option).  A proposal:

! | interface LowPowerListening
! | {
! |   async command result_t SetMode(lpl_mode_t mode);
! |   async command lpl_mode_t GetMode();
! |   async command result_t SetListeningMode(lpl_mode_t mode);
! |   async command lpl_mode_t GetListeningMode();
! |   async command result_t SetTransmitMode(lpl_mode_t mode);
! |   async command lpl_mode_t GetTransmitMode();
! | }

       The lpl_mode_t values are mapped by the specific radio implementation
***************
*** 163,173 ****
       dependent manner

! interface CC1000LowPowerListening
! {
!   async command result_t SetPreambleLength(uint16_t bytes);
!   async command uint16_t GetPreambleLength();
!   async command result_t SetCheckInterval(uint16_t ms);
!   async command uint16_t GetCheckInterval();
! }

       The "mode" options provide a level of abstraction above the 
--- 163,173 ----
       dependent manner

! | interface CC1000LowPowerListening
! | {
! |   async command result_t SetPreambleLength(uint16_t bytes);
! |   async command uint16_t GetPreambleLength();
! |   async command result_t SetCheckInterval(uint16_t ms);
! |   async command uint16_t GetCheckInterval();
! | }

       The "mode" options provide a level of abstraction above the 
***************
*** 185,192 ****
       specific to the CC1000 radio.

! interface RadioTimeStamping
! {
!   async event void SFD(uint16_t time, TOS_MsgPtr msgBuff);
! }

       Each platform may be able to provide more information than just the
--- 185,192 ----
       specific to the CC1000 radio.

! | interface RadioTimeStamping
! | {
! |   async event void SFD(uint16_t time, TOSMsg* msgBuff);
! | }

       Each platform may be able to provide more information than just the
***************
*** 194,205 ****
       with additional time information.

! interface CC1000RadioTimeStamping
! {
!   async event void startSymbol(uint8_t bitsPerBlock, uint8_t offset, TOS_MsgPtr msgBuff);
!   async event void byte(TOS_MsgPtr msg, uint8_t byteCount);
!   async event void blockTimer();
! }

!      The 16-bit "time" field of TOS_Msg is the 16-bit 32768Hz timer value
       corresponding to the SFD event.  Upper layers are responsible for 
       expanding the 16-bit 32768Hz value into a larger 32-bit or 64-bit
--- 194,205 ----
       with additional time information.

! | interface CC1000RadioTimeStamping
! | {
! |   async event void startSymbol(uint8_t bitsPerBlock, uint8_t offset, TOSMsg* msgBuff);
! |   async event void byte(TOSMsg* msg, uint8_t byteCount);
! |   async event void blockTimer();
! | }

!      The 16-bit "time" field of TOSMsg is the 16-bit 32768Hz timer value
       corresponding to the SFD event.  Upper layers are responsible for 
       expanding the 16-bit 32768Hz value into a larger 32-bit or 64-bit
***************
*** 216,314 ****
       the user to convert dB values into the virtual scale and vice versa.
       Radio timing information, such as bit, byte, and symbol times are
!      provided through the RadioControl interface.    
! 
! /**
!  * Radio control interface
!  * @author Joe Polastre
!  */
! interface RadioControl
! {
!   /**
!    * Set the TinyOS RF channel for this device.
!    *
!    * @param channel Desired TinyOS RF channel.  Must be between
!    *                zero and GetMaxChannels() - 1.
!    *
!    * @return SUCCESS if the RF channel was successfully changed
!    */
!   command result_t SetRFChannel(uint8_t channel);
! 
!   /**
!    * Get the TinyOS RF channel for this device.
!    * 
!    * @return TinyOS non-overlapping RF channel currently in use
!    */
!   command uint8_t GetRFChannel();
! 
!   /**
!    * Get the maximum number of RF channels available for this device
!    *
!    * @return n, where channels 0 to n-1 are non-overlapping channels
!    */
!   command uint8_t GetMaxChannels();
! 
!   /**
!    * Set the transmit RF power value.  
!    * Valid values are 0 through 255 corresponding to the relative
!    * radio power.  0 is minimum power, 255 is maximum power.
!    *
!    * @param power A power index between 0 and 255
!    * 
!    * @result SUCCESS if the radio power was adequately set.
!    *
!    */
!   command result_t SetRFPower(uint8_t power);	
! 
!   /**
!    * Get the present RF power index.
!    *
!    * @result The power index value between 0 and 255
!    */
!   command uint8_t GetRFPower();
! 
!   /**
!    * Convert an RFPower (0-255) relative setting to the actual
!    * DB setting
!    *
!    * @param power A power index between 0 and 255
!    *
!    * @result The corresponding output dBm of the input power level
!    */
!   command uint8_t RFtoDB(uint8_t power);
! 
!   /**
!    * Convert a dBm value to a relative RFPower value.
!    *
!    * If the radio cannot support the requested dBm value,
!    * it will return
!    * 
!    * @param dbm dBm output power to convert to relative RF value
!    *
!    * @result The corresponding RF power level (0-255)
!    */
!   command uint8_t DBtoRF(int8_t dbm);
! 
!   /**
!    * Read the value for the time to send a bit over the radio
!    *
!    * @return bit time in microseconds
!    */
!   command uint16_t getTimeBit();

!   /**
!    * Read the value for the time to send a byte over the radio
!    *
!    * @return byte time in microseconds
!    */
!   command uint16_t getTimeByte();

!   /**
!    * Read the value for the time elapsed in one radio symbol period
!    *
!    * @return symbol period in microseconds
!    */
!   command uint16_t getTimeSymbol();

! }

       The radio interfaces come together in the new RadioC module.
--- 216,264 ----
       the user to convert dB values into the virtual scale and vice versa.
       Radio timing information, such as bit, byte, and symbol times are
!      provided through the RadioControl interface.  See the RadioControl
!      interface defintion in tinyos-2.x/tos/interfaces

! | interface RadioControl
! | {
! |   command result_t SetRFChannel(uint8_t channel);
! |   command uint8_t GetRFChannel();
! |   command uint8_t GetMaxChannels();
! | 
! |   command result_t SetRFPower(uint8_t power);	
! |   command uint8_t GetRFPower();
! | 
! |   command uint8_t RFtoDB(uint8_t power);
! |   command uint8_t DBtoRF(int8_t dbm);
! | 
! |   command uint16_t getTimeBit();
! |   command uint16_t getTimeByte();
! |   command uint16_t getTimeSymbol();
! | }

!      The TOSMsg structure is created such that each radio implementation
!      may define its own header, footer, and metadata.  Since each
!      radio's layout will be distinct, common fields must be exposed
!      through a unified interface, known as RadioPacket.  
!      Platform indpendent services use RadioPacket to access common
!      message fields; whereas platform dependent services directly
!      access the TOSMsg fields as defined by that radio implementation.

! | interface RadioPacket
! | {
! |   command uint8_t getLength(TOSMsg* msg);
! |   command result_t setLength(TOSMsg* msg, uint8_t length);
! | 
! |   command uint8_t* getData(TOSMsg* msg);
! | 
! |   command uint16_t getAddress(TOSMsg* msg);
! |   command result_t setAddress(TOSMsg* msg, uint16_t addr);
! | 
! |   command uint16_t getGroup(TOSMsg* msg);
! |   command result_t setGroup(TOSMsg* msg, uint16_t group);
! | 
! |   command uint16_t getTime(TOSMsg* msg);
! | 
! |   command bool isAck(TOSMsg* msg);
! | }

       The radio interfaces come together in the new RadioC module.
***************
*** 318,369 ****
       users will wire to CSMARadioC; however RadioC provides a more general
       fallback for cross-platform application development.
!      The configurations look like the following:
! 
! in tos/chips/CC2420:
! 
! configuration RadioC {
!   provides {
!     // split phase startup and shutdown of the radio
!     interface SplitControl;
!     // change frequency, power, etc.
!     interface RadioControl;
!     // send a message
!     interface Send;
!     // receive a message
!     interface ReceiveMsg as Receive;
!   }
! }
! implementation
! {
!   components CSMARadioC as CC2420RadioC;

!   SplitControl = CC2420RadioC;
!   RadioControl = CC2420RadioC;
!   Send = CC2420RadioC;
!   Receive = CC2420RadioC;
! }

! configuration CSMARadioC {
!   provides {
!     // split phase startup and shutdown of the radio
!     interface SplitControl;
!     // change frequency, power, etc.
!     interface RadioControl;
!     // send a message
!     interface Send;
!     // receive a message
!     interface ReceiveMsg as Receive;

!     // enable/disable csma, acks
!     interface CSMAControl;
!     // change the backoff on a per-packet basis
!     interface CSMABackoff;
!     // duty cycle the radio with preamble sampling
!     interface LowPowerListening;
!   }
! }
! implementation {
!   components CC2420RadioM ...
! }

  FUTURE WORK:
--- 268,324 ----
       users will wire to CSMARadioC; however RadioC provides a more general
       fallback for cross-platform application development.
!      The configurations look like the following, such as
!      in tos/chips/CC2420:

! | configuration RadioC {
! |  provides {
! |     // split phase startup and shutdown of the radio
! |     interface SplitControl;
! |     // change frequency, power, etc.
! |     interface RadioControl;
! |     // send a message
! |     interface Send;
! |     // receive a message
! |     interface Receive;
! |   }
! | }
! | implementation
! | {
! |   components CSMARadioC as CC2420RadioC;
! | 
! |   SplitControl = CC2420RadioC;
! |   RadioControl = CC2420RadioC;
! |   Send = CC2420RadioC;
! |   Receive = CC2420RadioC;
! | }

!      Then, if the radio supports CSMA, it also provides a
!      CSMARadioC configuration.  Services wire to RadioC to be
!      radio-agnostic, and CSMARadioC if they wish to use the CSMA
!      control functionality but restrict their service's portability
!      to CSMA radios.

! | configuration CSMARadioC {
! |   provides {
! |     // split phase startup and shutdown of the radio
! |     interface SplitControl;
! |     // change frequency, power, etc.
! |     interface RadioControl;
! |     // send a message
! |     interface Send;
! |     // receive a message
! |     interface ReceiveMsg as Receive;
! | 
! |     // enable/disable csma, acks
! |     interface CSMAControl;
! |     // change the backoff on a per-packet basis
! |     interface CSMABackoff;
! |     // duty cycle the radio with preamble sampling
! |     interface LowPowerListening;
! |   }
! | }
! | implementation {
! |   components CC2420RadioM ...
! | }

  FUTURE WORK:
***************
*** 381,384 ****
  | Berkeley, CA 94720
  |
! | email - polastre at cs.berkeley.edu

--- 336,339 ----
  | Berkeley, CA 94720
  |
! | email - polastre AT cs.berkeley.edu