View source for IoT Mesh Firmware User Manual

=INTRODUCTION=
Dragino IoT Mesh Firmware is designed to use Dragino products for Internet of Things project. This firmware can be loaded in below products:
*Linux IoT Appliance: [http://www.dragino.com/products/mother-board.html <span CLASS=bluetext>MS14-S or MS14-P</span>]
*Linux IoT WiFi Modyle: [http://www.dragino.com/products/linux-module.html <span CLASS=bluetext>HE</span>]
*Linux , WiFi Shield for Arduino: [http://www.dragino.com/products/yunshield.html <span CLASS=bluetext>Yun Shield</span>]
*All other products designed base on HE module


This page is a user manual for the Dragino IoT Mesh Firmware. The manual is written as a <span CLASS=greentext>FULL HARDWARE VERSION</span>. Some of above products may not work with a feature if it doesn't have the required connector/peripheral hardware for this feature.
<br>
<br>

=DEFAULT LOG IN/PASSWORD=
The IoT Mesh Firmware provide SSH, Web GUI or RS232 access. Default Log in and AP password is:
 SSH/ WEB Log in: 
 <span CLASS=subtitle>username: root</span>
 <span CLASS=subtitle>password: dragino</span>

 WiFi AP password:
 <span CLASS=subtitle>dragino-dragino</span>

Detail method to access are as below: 

==Fall Back IP==
A fall back IP 172.31.255.254/255.255.255.252 is assigned to the LAN port (eth0 interface) so user can always access the system with this ip via the IP 172.31.255.253/255.255.255.252.
[[File:set_windows_fallback_ip.jpg|500px|none|thumb|Set windows ip to access IoT Mesh Firmware via fall back ip]]



==SSH Access==
IoT Mesh Firmware bases on OpenWrt Linux system. User can access it via SSH and see the linux console. 

1/ You should know device's LAN port ip or WiFi ip, or use fall back ip. Then configure your computer to the same IP segment as the device. 

2/ Then run putty to access the device. default user name and password of is: 
 <span CLASS=subtitle>username: root</span>
 <span CLASS=subtitle>password: dragino</span>
[[File:putty_access.jpg|500px|none|thumb|Use putty to access the device]]

3/ Once login successfully, user should be able see below welcome page. 
[[File:putty_access_login.jpg|500px|none|thumb|SSH Welcome Page]]

==GUI Access==
The firmware also has built-in web server and provide friendly GUI access. put its ip on your browser and input username /password to access.
[[File:GUI_login.jpg|500px|none|thumb|GUI login, default username/password: root/dragino]]

[[File:GUI_status.jpg|500px|none|thumb|Status is pop up once login successfully. ]]



==RS232 Access==
The IoT Mesh firmware provide UART access. Developer can use a UART to RS232 converter to access the u-boot via its serial interface. 

[[File:Connect_ARU_to_ms14.png|500px|none|thumb|Example: Connect ARU to ms14 via UART]]

Configure the serial port with below parameters: 
Serial: 115200, 
Data: 8bits, 
Xon/Xoff enable

[[File:UART_configure_ms14.jpg|500px|none|thumb|ms14 serial port access]]

[[File:u-boot_ms14.jpg|500px|none|thumb|u-boot access via UART]]

<br>
<br>
==Default AP Password==
The default passwrod for AP access is <span CLASS=bluemiddle>dragino-dragino</span>


<br>
<br>

=TYPICAL NETWORK SETUP=
This section describes the typical network topology can be set via the Dragino IoT Mesh Firmware. 

Before setting network parameters, user can set up the <span CLASS=bluetext>Display Net Connection</span> under <span CLASS=greentext>Web --> NetWork --> Internet Access</span> for a easily to check network status. This option will display the network connection to specify host via SYS LED. The SYS LED will blink if the network connection is up. 
[[File:Check_Net_1.png|600px|none|thumb|Check Network Connection to a Host]]

<br>
<br>
==WiFi Client Mode==
<span CLASS=subtitle>Brief </span>In the WiFi Client Mode, Dragino acts as a WiFi client and gets DHCP from uplink router via WiFi. It also share the internet to its LAN port for other devices.
[[File:Network_WiFi_Client.png|600px|none|thumb|WiFi Client Mode]]

<br>
<span CLASS=subtitle>Set Up in Web UI</span>
*<span CLASS=bluetext>Internet Access</span> 
**Access Internet via '''WiFi Client'''
**Way to Get IP: '''DHCP'''
**Input correct '''SSID''', '''Password''' and '''Encryption'''. 


*<span CLASS=bluetext>LAN and DHCP</span> 
**Enable DHCP server in its LAN port


*<span CLASS=bluetext>Access Point</span>
**Disable WiFi AP


*<span CLASS=bluetext>Mesh Network</span>
**Disable WiFi Mesh Network


<br>
<br>
==General AP Mode==
<span CLASS=subtitle>Brief </span>In the General AP Mode, Dragino gets internet access from its WAN port or USB 3G/4G/GPRS. Dragino itself acts as a WiFi Access Point and provide a WiFi AP network. It share the internet to its AP network or LAN interface.
[[File:Network_AP_Mode.png|500px|none|thumb|Internet Access via WAN]]
[[File:Network_AP_Mode-1.png|500px|none|thumb|Internet Access via USB 3G/4G/GPRS]]

<br>
<span CLASS=subtitle>Set Up in Web UI</span>
*<span CLASS=bluetext>Internet Access</span> 
**Access Internet via '''WAN PORT''' or '''[[IoT_Mesh_Firmware_User_Manual#USB_Modem_Set_UP|USB Modem]]'''


*<span CLASS=bluetext>LAN and DHCP</span> 
**Enable DHCP server in its LAN port


*<span CLASS=bluetext>Access Point</span>
**Enable WiFi AP
**Input SSID/ Encryption/ Passphrase


*<span CLASS=bluetext>Mesh Network</span>
**Disable WiFi Mesh Network

<br>
<br>

==Mesh WiFi Network==
<span CLASS=subtitle>Brief </span> in this network topology, user should choose the device to be a mesh gateway node or mesh client node 
*<span CLASS=bluetext>Mesh Gateway</span>: use WAN port or USB 3G to get internet access from uplink router. It also shares the internet to its Mesh Network for other Mesh Clients. The Mesh Gateway also acts as a DHCP router for its mesh network.
*<span CLASS=bluetext>Mesh Client</span>: Connects to the Mesh Gateway via mesh network, it also bridge internet via the LAN and WiFi AP interface.

[[File:Network_Mesh_Network_1.png|600px|none|thumb|Dragino to set up a mesh network]]

<span CLASS=subtitle>Mesh Gateway Set Up</span>
*<span CLASS=bluetext>Internet Access</span> 
::Access Internet via '''WAN PORT''' or '''[[IoT_Mesh_Firmware_User_Manual#USB_Modem_Set_UP|USB Modem]]'''
[[File:Network_Mesh_GW_1.png|400px|none|thumb|Select Internet Connection Method for mesh gateway]]
*<span CLASS=bluetext>LAN and DHCP</span> 
::Enable DHCP server in its LAN port and Set Gateway to 255.255.255.255
[[File:Network_Mesh_GW_21.png|400px|none|thumb|Enable DHCP Server]]
*<span CLASS=bluetext>Access Point</span>
::Enable WiFi AP, Can set same SSID in the mesh network
[[File:Network_Mesh_GW_3.png|400px|none|thumb|Enable WiFi AP, not necessary]]
*<span CLASS=bluetext>Mesh Network</span>
::Enable WiFi Mesh Network
::Input Mesh Group     //Note: Mesh Device within same group can  communicate with each other. In version < 3.1.2, it use BSSID for different mesh group, Mesh Group is a translation for BSSID for easy configure and remember. 
[[File:Network_Mesh_GW_51.png|400px|none|thumb|Define mesh group]]


<span CLASS=subtitle>Mesh Client Set Up</span>
*<span CLASS=bluetext>Internet Access</span> 
::Access Internet set to '''Disable'''
[[File:Network_Mesh_Client_11.png|400px|none|thumb|Disable internet connection]]
*<span CLASS=bluetext>LAN and DHCP</span> 
::Disable DHCP server in its LAN port and set gateway point to mesh gateway.
[[File:Network_Mesh_Client_21.png|400px|none|thumb|Disable DHCP Server. ]]
*<span CLASS=bluetext>Access Point</span>
::Enable WiFi AP (can use same SSID or difference SSID with other mesh node)
[[File:Network_Mesh_Client_3.png|400px|none|thumb|Enable WiFi AP, not necessary]]
*<span CLASS=bluetext>Mesh Network</span>
::Enable WiFi Mesh Network
::Input Mesh Group     //Note: Mesh Device within same group can  communicate with each other.In version < 3.1.2, it use BSSID for different mesh group,Mesh Group is a translation for BSSID for easy configure and remember. 
[[File:Network_Mesh_GW_51.png|400px|none|thumb|Define mesh group]]

<br>
<br>

==USB Dial Up Modem Set Up==
Dragino USB interface can be used for GPRS/3G/4G connection. Below are some set up examples.
[[File:Network_USB_Modem.png|600px|none|thumb|3G WCDMA Set Up Example for China Unicom]]
[[File:Network_USB_Modem_1.png|600px|none|thumb|3G EV-DO/CDMA2000 Set Up Example for China Telecom]]
<br>
<br>

==USB 3G/4G Ethernet Dongle==
Some USB dongles are not use the dial up to connect internet. Instead, they appear as a network interface and has built-in router feature. Huawei Hilink dongles are a typical of these. when user plug such dongle into computer, it will auto connect to Internet and redirect to a web interface, when plug such dongle into the MS14, a new interface will appear (typicllay <span CLASS=bluetext>eth2</span>eth2 or <span CLASS=bluetext>usb0</span>) by running command "<span CLASS=bluetext>ifconfig -a</span>"

Since <span CLASS=bluetext>firmare v3.1.2</span>, user can use the Web UI to configure use these dongle for internet connection direclty. 

[[File:Network_USB_Eth_Modem-1.png|600px|none|thumb|a new interface generate by USB ethernet modem]]

[[File:Network_USB_Eth_Modem-2.png|600px|none|thumb|Configure Ethetnet USB modem]]

<br>
<br>

=INTERNET OF THINGS APPLICATIONS=
==Introduction==
The IoT Mesh Firwmare provides a set of Web UI and scripts specially design for Internet of Things Applications. With these features, users can easily to set up/ develope IoT application using the Dragino Products.
<br>
<br>

==PowerUART UI==
In the PowerUART setting page, user can set the Dragino UART interface working in three different operation modes:
<br>
===Linux Console/Arduino Bridge===
In this mode, the Linux console is enable at <span CLASS=bluetext>115200 baud rate</span>. User can send command to Linux and debug it via UART interface by connecting a UART to RS232/USB module to the device. 

This mode also support limited [http://arduino.cc/en/Reference/YunBridgeLibrary Arduino Bridge Library] which provides easy communication when connect an AVR MCU to the UART interface . Current firmware supports the process/console/file class in Bridge library. 
<span CLASS=redtext>note:</span> The Bridge library baud rate in Arduino IDE is 250000 by default. User should change it to 115200 in the file <span CLASS=bluetext>arduino1.5.x\libraries\Bridge\src\Bridge.h</span> to match the linux kernel baud rate. change example as below:

in Bridge.h file:
 // This subclass uses a serial port Stream
 class SerialBridgeClass : public BridgeClass {
  public:
    SerialBridgeClass(HardwareSerial &_serial)
      : BridgeClass(_serial), serial(_serial) {
      // Empty
    }
 
    void begin(unsigned long baudrate = 250000) {    // <span CLASS=redtext>change this to 115200</span>
      serial.begin(baudrate);
      BridgeClass::begin();
    }
 
  private:
    HardwareSerial &serial;
 };

<br>

===UART Routing===
In this mode, Linux console is disable. And a uart_routing script is running in backgroud to monitor the data received, it will then dispatch this data according to match pattern and pre-config path. 
[[File:uart_routing_0.png|600px|none|thumb|UART Routing]]

The match pattern is [http://www.lua.org/manual/5.1/manual.html#5.4.1 Lua match pattern]. 

Example: in below setting, the script will match the temperature and humidity value arrived at the UART and save them to the /var/iot/channels path. These value can be then used for other applications. 
[[File:uart_routing.png|600px|none|thumb|UART routing config example]]
<br>

===Disable Linux Console===
In this mode, The Linux Console is disable and the UART is free. User is free to call the UART interface in their application. 

<br>
<br>

==IoT Services==
===General Set Up===
The IoT Services page provide the configure detail for how the device should communicate with the IoT Servers. 
[[File:IoT_Service_Setup.png|600px|none|thumb|General IoT Service Configure Page]]
<br>
<br>

===Xively Server===
Xively Detail Example: 
[[File:IoT_Service_Xively.png|600px|none|thumb|Xively Server set up example]]
After the configure, the device will link the local channle id (in /var/iot/channels/) and Xively Channel ID. It will auto post data to Xively server every one minutes. So user only need to change the local value in their applications, this can be done via [IoT_Mesh_Firmware_User_Manual#UART_Routing UART Routing], Arduino Bridge Library or other methods. 

[[File:YunExample_DHT11_3.png|500px|none|thumb|Result in Xively server]]

<br>
<br>
===TCP Client===
In TCP Client mode, device will establish a TCP connection to a TCP server. The device will use this connection to send local sensor data to the remote TCP server or get data from remote TCP server. 
[[File:TCP_Client_1.png|600px|none|thumb|Establish a Connection to a TCP Server]]
[[File:TCP_Client_2.png|600px|none|thumb|Channels Configure Example]]
[[File:TCP_Client_3.png|600px|none|thumb|Use a socket to test the TCP Client]]

<br>
<br>

==Lua Match Pattern==
The match pattern use in the Web UI is Lua Match Pattern, reference link is [http://www.lua.org/manual/5.1/manual.html#5.4.1 Lua match pattern].

<br>
<br>

=Reset Network or Reset to System Default=
The IoT firmware attached the reset feature to the toggle button which can be used for reset. When IoT firmware is running, user can press the toggle button(GPIO11) to reset the device. 
*Pressing the toggle button , the SYS LED(GPIO28) will blink, release the button after 5 seconds, device will reset the network setting and reboot (SYS/LAN/WAN/WiFI blink once), other settings will be kept.
*Pressing the toggle button , the SYS LED(GPIO28) will blink, release the button after 30 seconds, device will reset ALL the setting to factory default and reboot((SYS/LAN/WAN/WiFI blink once) .
<br>
<br>

=UPGRADE FIRMWARE=

[[Upgrade_Firmware_ms14|Refer this link for how to upgrade firmware]]

<br>
<br>

=FIRMWARE RELEASE NOTE=
[[Mesh_IoT_Firmware|Mesh Firmware Release Note]]

=CHANGE NETWORK CONFIGURE FILES=
The IoT Mesh Firmware use SECN script to configure the network part of linux. Each time there is Web UI submit for network change, the firmware will save the configure from WEB--> network and then call the file <span CLASS=bluetext>/usr/bin/config_secn</span> and  change the /etc/config/network parameters.  So if user need to change the network behavior to make it different from the current feature. they should change the config_secn file, otherwise, there change in /etc/config/network will be overridden after Web --> Network change.