/**************************************************************************************************
  Filename:       topo.h
  Description:    ZigBee network topology report + serial terminal (4-node teaching experiment).

                  Every node prints its own "network ID card" over the serial port so that
                  students can read the parent/child relations, the depth and the link quality
                  of each node and then draw the network topology by hand.

                  The same serial port also accepts a few single-character commands
                  (see "terminal commands" below), so a student can ask for a report
                  at any moment instead of waiting for the automatic one.

                  No ZDO round trip and no extra OSAL task is required: all values are read
                  synchronously from the local NIB, the association list and the neighbour table.
**************************************************************************************************/

#ifndef TOPO_H
#define TOPO_H

#ifdef __cplusplus
extern "C" {
#endif

/**************************************************************************************************
 *                                            INCLUDES
 **************************************************************************************************/
#include "ZComDef.h"

/**************************************************************************************************
 *                                      CONSTANTS / CONFIG
 **************************************************************************************************/

/* Serial port used for the report and for the terminal commands.
 * Keep it identical to the port opened by zclSampleSw_InitUart() (HAL_UART_PORT_0).
 * The SampleSwitch application configures that port for 115200 baud, 8N1. */
#define TOPO_UART_PORT            0

/* Size of the small output buffer.
 * The buffer is flushed automatically whenever it is full, so this value does NOT
 * limit the length of a report line: a longer line is simply transmitted in
 * several UART writes. It only trades UART calls against XDATA.
 * Keep it small - the CC2530 has 8 KB of XDATA and this project uses almost all of it. */
#define TOPO_LINE_BUF_LEN         16

/* Period of the application timer that drives this module.
 * zcl_samplesw.c must start SAMPLESW_TOPO_EVT every TOPO_TICK_MS milliseconds.
 * Keep it a divisor of 1000 so that seconds can be printed with a simple divide.
 * It is also the pace at which a report is emitted (see TOPO_LINES_PER_PASS). */
#define TOPO_TICK_MS              100

/* How many report lines are emitted per TOPO_TICK_MS.
 *
 * A whole report is about 600 bytes, but the UART DMA transmit buffer holds only
 * about 256 bytes and HalUARTWrite() DROPS data once it is full.  Emitting the
 * report in small slices keeps every UART burst short enough for the DMA buffer,
 * so nothing is ever lost.
 * 3 lines of at most ~55 bytes = ~165 bytes per tick, which is a safe margin. */
#define TOPO_LINES_PER_PASS       3

/* Default interval of the automatic report, in milliseconds (0 = switched off). */
#define TOPO_REPORT_MS_DEFAULT    10000

/* Step used by the '+' and '-' terminal commands, in milliseconds. */
#define TOPO_REPORT_MS_STEP       5000

/* Upper limit of the report interval accepted from the terminal, in milliseconds. */
#define TOPO_REPORT_MS_MAX        60000

/**************************************************************************************************
 *                                    TERMINAL COMMANDS
 *
 *   t   print the topology report immediately
 *   p   switch the automatic report on / off
 *   +   report interval + TOPO_REPORT_MS_STEP
 *   -   report interval - TOPO_REPORT_MS_STEP
 *   h   print the command list (also '?')
 *
 **************************************************************************************************/

/**************************************************************************************************
 *                                        EXTERNAL FUNCTIONS
 **************************************************************************************************/

/* Print one complete network topology report over TOPO_UART_PORT.
 * Task context only (it writes a few hundred bytes to the UART). */
extern void Topo_Print( void );

/* Feed one received serial byte.
 * Safe to call from the HAL UART callback (possibly interrupt context):
 * it only stores the byte, it never prints anything. */
extern void Topo_RxByte( uint8 ch );

/* Drive the module: handle a pending terminal command and / or the automatic report.
 * Must be called from the application task event handler in task context,
 * every TOPO_TICK_MS milliseconds. */
extern void Topo_Tick( void );

#ifdef __cplusplus
}
#endif

#endif /* TOPO_H */

/**************************************************************************************************
**************************************************************************************************/