+ readme content

README.md

@@ -1,6 +1,127 @@
 # nano Bus
 
 Protocol stack for Body Area Network Modules. The nBus protocol is an application layer protocol for connecting sensor nodes to a higher-level control unit in the BAN. The main development goal is to provide a reliable and secure way for real-time monitoring and feedback of health parameters during clinical or home rehabilitation and physiotherapy.
+
+## How to integrate to project
+The basic control structure is ```nBusPlatformInterface_t```. You have to define basic functions whtch will be interact with protocol stack
+```c
+typedef  struct{
+void (*uart_receive)(uint8_t *data, int n);  // Start reciving n bytes and store in to data array. 
+                                             // In interrupt mode.
+void (*uart_transmit)(uint8_t *data, int n); // Send n bytes stored n data array
+void (*uart_abort_receive)();                // Abort inomming receive process
+void (*led_on)(void);                        // turn on signaliation LED 
+void (*led_off)(void);                       // turn off signaliation LED 
+void (*led_toggle)(void);                    // toggle signaliation LED 
+void (*timer_uart_start)(int n);  // start timer for receiveng b bytes
+                                  // It will be used to detect IDLE state in RX 
+void (*timer_uart_stop)(void);    // stop timer
+}nBusPlatformInterface_t;
+```
+**Communication timer configuration:**
+- Timer used in ``timer_uart_start`` functino have to be preconfigured to time period equivalent to time needed to receive 1 byte. This time depend on selected communication speed of UART interface.
+- Timer have to tun in interrupt mode.
+
+In application, the 2 more callback have to be defined:
+- UART Complete Receive Callback - when requested data are received. 
+- TIMER Period Elapsed - when timer period is elapsed
+These 2 calback have to be imeplement as follows:
+```c
+static  inline  void  nbus_app_UART_RX(){
+    nbus_cb_UART_RX();  // call function in nBus stack
+}
+
+static  inline  void  nbus_app_TIM_periodElapsed(){
+   nbus_cb_TIM_periodElapsed(); // call function in nBus stack
+}
+```
+###  Practical integration
+
+**Create platform driver**
+```c
+nBusPlatformInterface_t hw_platform ={
+    uart_receive_it,  // these are pointers to existing functions
+    uart_send,
+    uart_abort_receive,
+    led_on,
+    led_off,
+    led_toggle,
+    timer_uart_start,
+    timer_uart_stop
+};
+```
+
+**Initialise and start application**
+```c
+nbus_init(getDummyDriver(), &hw_platform);
+nbus_init_app(NULL, NULL);
+```
+where ``getDummyDriver()`` return pointer to structure ``nBusAppInterface_t``, which implement specific sensors.
+Every sensors/device have to implement the basic functions:
+```c
+typedef  struct{
+    void (*init)(void *hw_interface, void *hw_config);
+    void (*reset)();
+    nBus_sensorType_t(*getType)(uint8_t sensor_index);
+    uint8_t (*getSensorCount)();
+    uint8_t (*getData)(uint8_t sensor_index, uint8_t *data);
+    uint8_t (*setData)(uint8_t *data);
+    uint8_t (*hasParam)(uint8_t sensor_index, nBus_param_t param_name);
+    uint8_t (*getParam)(uint8_t sensor_index, nBus_param_t param_name);
+    nBus_param_t (*setParam)(uint8_t sensor_index, nBus_param_t param_name, uint8_t param_value);
+    void (*start)();
+    void (*stop)();
+}nBusAppInterface_t;
+```
+
+***Provide EEPROM configuration memory interface***
+
+```c
+nBus_MemoryDriver memory_ec20 = {
+    DS28EC20_init,
+    DS28EC20_readData4B,
+    DS28EC20_readData2B,
+    DS28EC20_writeData4B,
+    DS28EC20_writeData2B,
+    DS28EC20_getId
+};
+memory_ec20.init(ONE_WIRE_GPIO_Port, ONE_WIRE_Pin);  //applicatin level function call
+nbus_init_memory_driver(&memory_ec20, 16);  // pass memory driver to nBus
+```
+
+***Run application stack***
+
+```c
+nbus_stack();
+```
+## nBus interface
+nBus interface is pointer to structure ``nBusAppInterface_t``. It contains these functions:
+- ``void  init(void *hw_interface, void *hw_config);``
+   - Configure hardwre module/sensor. ``hw_interface`` can represent communication bus or ``NULL``.
+   - ``hw_config`` can store configuration data for module or ``NULL``.
+- ``void  reset();``
+   - reset connected device/sensor. Can be empty.
+- ``nBus_sensorType_t getType(uint8_t sensor_index);``
+  - return type of sensor connected to module. The ``sensor_index`` points to specific sensor.
+- ``uint8_t  dummy_getSensorCount(void);``
+  - return number of connected sensors in module.
+- ``uint8_t getData(uint8_t sensor_index, uint8_t *data);``
+  - read data from ``sensor_index``-th sensor in module. 
+  - return number of readed bytes,
+  - data are stored to parameter ``data``.
+- ``uint8_t setData(uint8_t *data);``
+  - send data to sensor. Only for outut modules.
+  - return number of written bytes.
+- ``uint8_t getParam(uint8_t sensor_index, nBus_param_t param);``
+  - return paramater value of scpecific ``param`` on  ``sensor_index``-th sensor in module
+- ``uint8_t hasParam(uint8_t sensor_index, nBus_param_t param);``
+  - test to existence ``param`` on ``sensor_index``-th sensor in module
+- ``nBus_param_t setParam(uint8_t sensor_index, nBus_param_t param, uint8_t value);``
+  - set ``value`` of  ``param`` on ``sensor_index``-th sensor in module
+  - return ``param`` 
+
+## nBus protocol description
+
 The communication is a master/slave request/response, allowing not only node addressing but also specific sensor addressing, as a communication node might consist of sensors as well as actuators. Packet structure consists of a link frame and an application packet as shown following figure.
 
 ![nBus Frame](/assets/nBusFrame.png)