Diff: stm-spirit1-rf-driver/SimpleSpirit1.h

Revision:

73:a1342eb7974c

Parent:

72:413cb97ac077

Child:

74:7672516efa2a

--- a/stm-spirit1-rf-driver/SimpleSpirit1.h	Fri Jul 21 13:54:39 2017 +0200
+++ b/stm-spirit1-rf-driver/SimpleSpirit1.h	Fri Jul 21 15:18:37 2017 +0200
@@ -58,6 +58,43 @@
 /*** A Simple Spirit1 Class ***/
 // NOTE: must be a singleton (due to mix of MBED/CUBE code)!!!
 // NOTE: implementation is IRQ-save but (intentionally) NOT thread-safe!!!
+/** Simple Spirit1 Class
+ *
+ * @Note Synchronization level: implementation is IRQ-save but (intentionally) NOT thread-safe!!!
+ *
+ * Example:
+ * @code
+ * #include "mbed.h"
+ * #include "SimpleSpirit1.h"
+ *
+ * static char *send_buf = "Hello World!";
+ *
+ * static SimpleSpirit1 &myspirit = SimpleSpirit1::CreateInstance(D11, D12, D3, D9, D10, D2);
+ *
+ * static volatile bool tx_done_flag = false;
+ *
+ * static void callback_func(int event)
+ * {
+ *   if (event == SimpleSpirit1::TX_DONE) {
+ *     tx_done_flag = true;
+ *   }
+ * }
+ *
+ * int main()
+ * {
+ *   myspirit.on();
+ *
+ *   while(1)
+ *   {
+ *     size_t curr_len = strlen((const char*)send_buf);
+ *     myspirit.send(send_buf, curr_len);
+ *
+ *     while(!tx_done_flag);
+ *     tx_done_flag = false;
+ *   }
+ * }
+ * @endcode
+ */
 class SimpleSpirit1 {
  protected:
 	static SimpleSpirit1 *_singleton;
@@ -388,7 +425,6 @@
      * @param sdn  'PinName' of pin to use for device shutdown
      *
      * @returns     reference to singleton instance
-     *
      */
     static SimpleSpirit1& CreateInstance(PinName mosi, PinName miso, PinName sclk,
     		PinName irq, PinName cs, PinName sdn,
@@ -415,7 +451,6 @@
      * @param sdn  'PinName' of pin to use for device shutdown
      *
      * @returns     reference to singleton instance
-     *
      */
     static SimpleSpirit1& Instance() {
     	if(_singleton == NULL) {
@@ -432,18 +467,15 @@
      *  @note  Function 'func' will be executed in interrupt context!
      *  @note  Function 'func' will be call with either 'RX_DONE', 'TX_DONE', or 'TX_ERR' as parameter
      *         to indicate which event has occurred.
-     *
      */
     void attach_irq_callback(Callback<void(int)> func) {
     	_current_irq_callback = func;
     }
 
     /** Switch Radio On
-     *
      */
     int on(void);
     /** Switch Radio Off
-     *
      */
     int off(void);
 
@@ -462,7 +494,6 @@
      * @returns             zero in case of success, non-zero error code otherwise
      *
      * @note                the maximum payload size in bytes allowed is defined by macro 'SPIRIT1_MAX_PAYLOAD'
-     *
      */
     int send(const void *payload, unsigned int payload_len, bool use_csma_ca = true);
 
@@ -474,31 +505,26 @@
      * @returns         number of bytes copied into the buffer
      *
      * @note            the buffer should be (at least) of size 'SPIRIT1_MAX_PAYLOAD' (in bytes).
-     *
      */
     int read(void *buf, unsigned int bufsize);
 
     /** Perform a Clear-Channel Assessment (CCA) to find out if there is a packet in the air or not.
      *
      * @returns  1 if packet has been seen.
-     *
      */
     int channel_clear(void);
 
     /** Check if the radio driver has just received a packet
-     *
      */
     int get_pending_packet(void);
 
     /** Is radio currently receiving
-     *
      */
     bool is_receiving(void) {
     	return _is_receiving;
     }
 
     /** Get latest value of RSSI (in dBm)
-     *
      */
     float get_last_rssi_dbm(void) {
     	get_last_rssi_raw();
@@ -506,7 +532,6 @@
     }
 
     /** Get latest value of RSSI (as Spirit1 raw value)
-     *
      */
     uint8_t get_last_rssi_raw(void) {
     	if(last_rssi == 0) {
@@ -516,7 +541,6 @@
     }
 
     /** Get latest value of LQI (scaled to 8-bit)
-     *
      */
     uint8_t get_last_sqi(void) {
     	const uint8_t max_sqi = 8 * ((SYNC_LENGTH>>1)+1);
@@ -529,7 +553,6 @@
     }
 
     /** Reset Board
-     *
      */
     void reset_board() {
     	init();