Indigresso Wiki

Open Source Stuff for DASH7

User Tools

Site Tools


Session Module (OTlib)

OpenTag Session Module. To be completed.


The code from session.h is pasted below, although you can also check the doxygen code documentation.

#include "OT_types.h"

/** Mode 2 Session Struct
  * The session struct is a 12 byte message container that is passed between
  * many layers
  * counter     (ot_uint) A number of ti until the session is scheduled to
  *             begin.  This is, in fact, an event timeout.
  * netstate    (ot_u8) A code representing what kind of session is underway,
  *             as well as a network association state.
  * channel     (ot_u8) primary channel ID that the session is using.
  * subnet      (ot_u8) This is the subnet value of the session.  It is loaded
  *             when a session becomes associated.
  * dialog_id   (ot_u8) This is the dialog value of the session, which is loaded
  *             when a session is associated.  It is a random number that needs
  *             to be provided if instantiating the session, or loaded from the
  *             request if you are attaching to the session.
  * flags       (ot_u8) Protocol Flags viable to the session.  These are aligned
  *             with the flag values from M2NP/M2QP, but they are generic enough
  *             that they could be used for other dialog-based protocols, too.

/** Session Network State Flags
  * Used in the m2session.netstate container for the unassoc-synced-
  * connected-assoc state transition.  The secondary purpose is for other types 
  * of state transitions.

#define M2_NETSTATE_TMASK           0x70
#define M2_NETSTATE_REQTX           0x00
#define M2_NETSTATE_RESPTX          0x10
#define M2_NETSTATE_REQRX           0x20            // set after valid request received
#define M2_NETSTATE_RESPRX          0x30
#define M2_NETFLAG_FLOOD            0x40
#define M2_NETFLAG_SCRAP            0x80

#define M2_NETSTATE_SMASK           0x03
#define M2_NETSTATE_INIT            0x08
#define M2_NETSTATE_DSDIALOG        0x04
#define M2_NETSTATE_UNASSOC         0x00
#define M2_NETSTATE_SYNCED          0x01            // set after valid synchronizer received
#define M2_NETSTATE_CONNECTED       0x02            // set after connecting to session
#define M2_NETSTATE_ASSOCIATED      0x03            // (Synced + connected)

/** Session power configuration
  * Used in the m2session.cs_rssi, .cca_rssi, .tx_eirp containers to 
  * move power configurations between layers.
#define M2_RSSI_AUTOSCALE           b10000000
#define M2_RSSI_MASK                b00011111
#define M2_RSSI_DBM(VAL)            (ot_int)(-140 + ((VAL)*3))
#define M2_EIRP_AUTOSCALE           b10000000
#define M2_EIRP_MASK                b01111111
#define M2_EIRP_DBM(VAL)            (ot_int)(-40 + ((VAL)>>1))
#define M2_EIRP_0p5DBM(VAL)         (ot_int)(-80 + (VAL))

/** Protocols (Translated)
#define M2_PROTOCOL_M2NP            0x51
#define M2_PROTOCOL_M2QP            0x51
#define M2_PROTOCOL_M2DP            0x60
#define M2_PROTOCOL_M2ADVP          0xF0
#define M2_PROTOCOL_M2RESP          0xF1

/** Session persistent flags
  * Used in the m2session.flags, to pass common flags between layers.
  * The flag values are consistent with the ones used for M2NP/M2QP, but they
  * can be used for other protocols, too, since they are pretty generic.
#define M2_FLAG_LISTEN              b10000000
#define M2_FLAG_DLLS                b01000000
#define M2_FLAG_VID                 b00100000
#define M2_FLAG_NLS                 b00010000

typedef struct {
    ot_u16  counter;
    ot_u8   channel;
    ot_u8   dialog_id;
    ot_u8   netstate;
    ot_u8   subnet;
    ot_u8   protocol;
    ot_u8   flags;
} m2session;

/** @brief  Initializes the Session module.  Run on startup.
  * @param  none
  * @retval none
  * @ingroup Session
void session_init();

/** @brief  Reduces the session counters uniformly, and alerts if a session is beginning
  * @param  elapsed_ti      (ot_uint) ti to reduce all session counters by
  * @retval ot_bool         True/False on session event timeout / no timeout
  * @ingroup Session
ot_bool session_refresh(ot_uint elapsed_ti);

/** @brief  Adds a session element to the heap, pushes it to stack, and sorts
  *         the stack so the session at the top is the one happening soonest.
  * @param  new_counter     (ot_u16) new session initial counter value
  * @param  new_netstate    (ot_u8) new session netstate value
  * @param  new_channel     (ot_u8) new session channel id
  * @retval m2session*      Pointer to added session struct
  * @ingroup Session
  * Additional session data not supplied as parameters to this function must be
  * loaded-in by the user, via the returned pointer.
m2session* session_new(ot_u16 new_counter, ot_u8 new_netstate, ot_u8 new_channel);

/** @brief  Returns true if there is already a session scheduled on supplied channel
  * @param  chan_id         (ot_u8) channel id to check for occupancy
  * @retval none
  * @ingroup Session
  * The Mode 2 Session Layer is not supposed to ever allow two sessions to be 
  * _scheduled_ on a single channel, at any given time (the reason for this, by 
  * the way, is to provide a way to avoid hitting the same background packets 
  * multiple times).  The user can call this function before running a scan, in
  * order to potentially cancel the scan before it starts.
  * Ad-hoc sessions (counter set initially to 0) are exempt from any such rules.
ot_bool session_occupied(ot_u8 chan_id);

/** @brief  Pops a session off the top of the stack (deleting it).
  * @param  none
  * @retval none
  * @ingroup Session
void session_pop();

/** @brief  Flushes (pops) expired sessions out of the stack.
  * @param  none
  * @retval none
  * @ingroup Session
void session_flush();

/** @brief  Flushes (pops) expired sessions out of the stack, but not the top session.
  * @param  none
  * @retval none
  * @ingroup Session
void session_drop();

/** @brief  Returns the number of sessions in the stack (zero indexed)
  * @param  none
  * @retval ot_int		Number of sessions in the stack.  -1 = empty
  * @ingroup Session
ot_int session_count();

/** @brief  Returns the session at the top of the stack.
  * @param  none
  * @retval m2session*   Session at top of stack
  * @ingroup Session
  * The stack is sorted, so the session that is pending the soonest is on top.
m2session* session_top();
opentag/otlib/session.txt · Last modified: 2012/03/12 01:31 by jpnorair