doc: add doc for peripheral connection and mux, improve coap example doc, minor fix

Signed-off-by: Yuguo Zou <[email protected]>

Author: YuguoWH

doc/documents/getting_started/getting_started.rst

@@ -92,6 +92,12 @@ See the following procedures to check peripherals and board settings. The periph
 
    hardware_requirement.rst
 
+
+.. toctree::
+   :maxdepth: 1
+
+   peripheral_preparation.rst
+
 Running a Sample Application
 ############################
 

doc/documents/getting_started/peripheral_preparation.rst

@@ -0,0 +1,67 @@
+.. _peripheral_preparation:
+
+Peripheral Preparation
+======================
+
+This is a quick manual helping you to connect your peripheral modules with your embARC boards.
+
+MUX Controller Setting
+######################
+On most of embARC boards, pins are multiplexed for various usages: uart, i2c, spi, etc. One pin can not be accessed by different usage simultaneously, that's where MUX controller comes in.
+We will take PMOD interface as example to explain the setting method. Other interfaces (Andruino, MikroBUS, etc.) can take PMOD as reference, and use the same method for setting.
+
+1. You need to find mux controller code at ``embarc_osp/board/[board_type]/drivers/mux``.
+One exception is board `The ARC IoT Development Kit (IoTDK) <https://www.synopsys.com/dw/ipdir.php?ds=arc_iot_development_kit>`_ which has fixed pin assignment and does **NOT** have mux controller.
+
+2. If you are using EMSK, go to mux.c and find ``io_mux_init()`` function, you will see it calls ``set_pmod_mux()`` with MUX options as parameters.
+MUX options are defined in mux.h and you could change them as you see fit.
+
+For example, You want to connect your EMSK with two i2c sensor modules. By default setting you only have PM2 as i2c interface.
+So now you have to check mux.h or EMSK manual to see if it support one more i2c interface.
+Notice that there is a ``PM3_I2C_GPIO_D`` macro in mux.h meaning that PM3 support i2c interface. Now all you need to do is to replace the default PM3 setting in ``set_pmod_mux()`` to ``PM3_I2C_GPIO_D``.
+Now your code should be like this:
+
+.. code-block:: c
+
+	set_pmod_mux(PM1_UR_UART_0 | PM1_LR_SPI_S	\
+				| PM2_I2C_HRI		\
+				| PM3_I2C_GPIO_D	\
+				| PM4_I2C_GPIO_D	\
+				| PM5_UR_SPI_M1 | PM5_LR_GPIO_A	\
+				| PM6_UR_SPI_M0 | PM6_LR_GPIO_A );
+
+.. note:: Notice that **UR** means Upper Layer of Pmod interface and **LR** means Lower Layer of Pmod
+
+3. If you are using HSDK, go to mux.c and find ``io_mux_init()`` function, you will see it calls ``creg_hsdc_set_gpio_mux()`` with paramater array ``gpio_mux_config`` as MUX options.
+By default all pins are set to GPIO, other MUX options are defined in ``PINMUX_TYPE`` in ``embarc_osp/device/inc/dev_pinmux.h``
+
+.. note:: To learn what interface your board has, please go to :ref:`board_bsp`
+
+PMOD Modules
+############
+
+PMOD WiFi Modules
+******************
+`Pmod WiFi <https://reference.digilentinc.com/reference/pmod/pmodwifi/start>`_ : Primary IC type is MRF24WG, use **SPI** and a few **GPIO** pins for data changing and controlling.
+Driver code at ``embarc_osp/device/peripheral/wifi/mrf24g``.
+
+RW009 WiFi : This type of module also uses **SPI** and **GPIO** pins for data changing and controlling.
+Driver code at ``embarc_osp/device/peripheral/wifi/rw009``.
+
+
+PMOD Temperature Module
+***********************
+`Pmod TMP2 <https://reference.digilentinc.com/reference/pmod/pmodtmp2/start>`_ : sensor chip type is ADT7420, use **I2C** for data collection.
+Driver code at ``embarc_osp/device/peripheral/sensor/temperature/adt7420``.
+
+`Pmod TMP3 <https://reference.digilentinc.com/reference/pmod/pmodtmp3/start>`_ : sensor chip type is TCN75A, use **I2C** for data collection.
+Driver code at ``embarc_osp/device/peripheral/sensor/temperature/tcn75``.
+
+Other PMOD or Compatible Modules
+********************************
+`Pmod AD2 <https://reference.digilentinc.com/reference/pmod/pmodad2/start>`_ : ADC type is AD7991, use **I2C** for data collection.
+Driver code at ``embarc_osp/device/peripheral/adc/ad7991``.
+
+`ESP01\/ESP01S <http://wiki.ai-thinker.com/esp8266/docs>`_ : Primary IC type is ESP8266, use **UART** interface for data changing and controlling.
+Driver code at ``embarc_osp/device/peripheral/wifi/slip_esp``.
+	The ESP01/ESP01S module is not originally a PMOD module, however it is PMOD campatible, which means you could wire it to PMOD interface on board. You need to connect GCC(embARC) to GCC(ESP) , 3.3V(embARC) to VCC, RXD(embARC) to TXD(ESP), and TXD(embARC) to RXD(ESP), respectively. Please take reference from datasheet of `ESP01\/ESP01S <http://wiki.ai-thinker.com/esp8266/docs>`_ and UART (type 4A) part of `Digilent Pmod Spec <https://www.digilentinc.com/Pmods/Digilent-Pmod_%20Interface_Specification.pdf>`_ for pin layout.

example/baremetal/blinky/README.rst

@@ -42,7 +42,7 @@ which have been installed in MetaWare IDE.
 .. code-block:: console
 
     $ cd <embarc_root>/example/baremetal/blinky
-    $ gmake BOARD=nism BD_VER=1506 CUR_CORE=arcemfull TOOLCHAIN=mw run
+    $ gmake BOARD=nsim BD_VER=1506 CUR_CORE=arcemfull TOOLCHAIN=mw run
 
 .. note:: Make sure you have selected the correct configuration of EMSK via dipswitches and that you have reset the board (button above “R”) to confirme its configuration
 

example/freertos/iot/coap/coap_server/README.rst

@@ -19,7 +19,7 @@ Detailed Description
     - Digilent PMOD TMP2
 
  * Design Concept
-    This example is designed to show how CoAP server running on FreeRTOS. We prepared three different resources which are helloworld string, temperature readings and LEDs. To demonstrate the function of CoAP server, we need to use CoAPthon as a CoAP client.
+    This example is designed to show how CoAP server running on FreeRTOS. We prepared three different resources which are helloworld string, temperature readings, and LEDs. To demonstrate the function of CoAP server, we need to use CoAPthon as a CoAP client.
 
  * Usage Manual
     This is an example running coap server on LwIP with FreeRTOS. The Pmod modules should be connected to ARC board.
@@ -30,14 +30,15 @@ Detailed Description
 Buidling and Running
 ********************
 
- This example outputs to the console. It is supported by all platform. The commands to run this example are as follows:
+ This example outputs to the console. It is supported by all platform. You might need to change mux configurations or connect wires in order to use peripheral modules, see :ref:`peripheral_preparation`.
+ The commands to run this example are as follows:
 
 .. code-block:: console
 
 	$ cd <embarc_root>/example/freertos/iot/coap/coap_server
 	$ make BOARD=emsk BD_VER=22 CUR_CORE=arcem7d TOOLCHAIN=gnu run
 
- When the WiFi is connected and CoAP server is running, you may run python code shown below. It uses CoAPthon packet as a CoAP Client and try to get and post resources from server. Please noted that the host IP should be replaced to the ipaddr shown on console.
+ When the WiFi is connected and CoAP server is running, you may run python code shown below. You may save this code as a .py file and run it from a new cmd console. The python code uses CoAPthon packet as a CoAP Client and try to get and post resources from server. Please noted that the host IP in python code should be replaced to the ipaddr shown on board uart console before running.
 
 .. code-block:: python