krzychb/esp-just-slip
<html> <h3>
<svg aria-hidden="true" class="octicon octicon-book" height="16" version="1.1" viewbox="0 0 16 16" width="16"/>
readme.md
</h3><article class="markdown-body entry-content" itemprop="text"><p>#esp-just-slip</p>
<p><a href=„https://en.wikipedia.org/wiki/Serial_Line_Internet_Protocol“>SLIP (Serial Line Internet Protocol)</a> provides easy to implement method to encapsulate data packets sent over a serial connection. The esp-just-slip is an implementation of SLIP prepared for <a href=„http://espressif.com/en/products/esp8266/“>ESP8266 SoC</a>. It is provided as C module <a href=„https://github.com/krzychb/esp-just-slip/blob/master/justslip“>justslip</a> and includes verification of data integrity with <a href=„https://en.wikipedia.org/wiki/Crc16“>CRC16</a>. Sample implementation of this module is available in file <a href=„https://github.com/krzychb/esp-just-slip/blob/master/user/user_main.c“>user_main.c</a> and demonstrates sending of data packets between arduino and ESP8266.</p> <p>##Implementation</p> <p>esp-just-slip can set data using hardware UART0 serial or using software serial. Software serial provides flexibility which other pins to use for communication if UART0 is already used for other purposes. Software serial is implemented using <a href=„https://github.com/plieningerweb/esp8266-software-uart“>esp8266 software uart</a> by <a href=„https://github.com/plieningerweb“>Andreas Plieninger</a>. To provide verification if data has been transmitted correctly <a href=„https://en.wikipedia.org/wiki/Crc16“>CRC16</a> is used.</p> <p>##Sample Test Scenarios</p> <p>Testing of this application using s/w and h/w serial ports may be performed with sample hardware configurations defined below.</p> <p>Please note that most of Arduino modules operate on 5V while ESP8266 on 3.3V To make the connection easier Arduino Pro Mini 3.3V has been used that provides direct compatibility of pin voltage to ESP8266. In other cases a 5V <> 3.3V voltage level shifter should be used or ESP8266 may be damaged if connected directly to 5V Arduino pins.</p> <p>###SLIP over S/W Serial - Hardware Set Up</p> <ul><li>Arduino Pro Mini 3.3V</li> <li>ESP-12E LoLin V3 with USB by wemos.cc</li> <li>Two USB-UART generic dongles used to <ul><li>monitor serial traffic received by ESP-12E</li> <li>upload Arduino and then monitor serial traffic received by Arduino</li> </ul></li> </ul><p><a href=„https://github.com/krzychb/esp-just-slip/blob/master/documents/just-slip-components-sws.jpg“ target=„_blank“><img src=„https://github.com/krzychb/esp-just-slip/raw/master/documents/just-slip-components-sws.jpg“ alt=„alt Sample configuration - components“/></a></p> <p>The following pins are used to connect particular modules:</p> <table><thead><tr><th>Module</th> <th>Pin Description</th> <th>Pin No.</th> <th><></th> <th>Pin No.</th> <th>Pin Description</th> <th>Module</th> </tr></thead><tbody><tr><td>ESP-12E</td> <td>Soft UART Rx</td> <td>GIPIO14</td> <td><></td> <td>11</td> <td>Soft UART Tx</td> <td>Arduino</td> </tr><tr><td>ESP-12E</td> <td>Soft UART Tx</td> <td>GIPIO15</td> <td><></td> <td>10</td> <td>Soft UART Rx</td> <td>Arduino</td> </tr><tr><td>ESP-12E</td> <td>Ground</td> <td>GND</td> <td><></td> <td>GND</td> <td>Ground</td> <td>Arduino</td> </tr><tr><td>ESP-12E</td> <td>UART1 Tx</td> <td>GPIO02</td> <td><></td> <td>Rx</td> <td>UART Rx</td> <td>USB-UART ESP</td> </tr><tr><td>ESP-12E</td> <td>Ground</td> <td>GND</td> <td><></td> <td>GND</td> <td>Ground</td> <td>USB-UART ESP</td> </tr><tr><td>Arduino</td> <td>UART Tx</td> <td>TXO</td> <td><></td> <td>Rx</td> <td>UART Rx</td> <td>USB-UART INO</td> </tr><tr><td>Arduino</td> <td>UART Rx</td> <td>RXI</td> <td><></td> <td>Tx</td> <td>UART Tx</td> <td>USB-UART INO</td> </tr><tr><td>Arduino</td> <td>Reset</td> <td>RST</td> <td><></td> <td>DTR</td> <td>UART DTR</td> <td>USB-UART INO</td> </tr><tr><td>Arduino</td> <td>Power Supply</td> <td>RAW</td> <td><></td> <td>5V</td> <td>Power Supply</td> <td>USB-UART INO</td> </tr><tr><td>Arduino</td> <td>Ground</td> <td>GND</td> <td><></td> <td>GND</td> <td>Ground</td> <td>USB-UART INO</td> </tr></tbody></table><p><a href=„https://github.com/krzychb/esp-just-slip/blob/master/documents/just-slip-connections-sws.jpg“ target=„_blank“><img src=„https://github.com/krzychb/esp-just-slip/raw/master/documents/just-slip-connections-sws.jpg“ alt=„alt Sample configuration - connections“/></a> Please refer to folder <a href=„https://github.com/krzychb/esp-just-slip/blob/master/documents“>documents</a> for additional pictures of connections.</p> <p>###SLIP over H/W Serial - Hardware Set Up</p> <ul><li>Arduino Pro Mini 3.3V</li> <li>ESP-01 with 3.3V power supply</li> <li>Two USB-UART generic dongles used to <ul><li>monitor serial traffic received by ESP-01</li> <li>upload Arduino and then monitor serial traffic received by Arduino</li> </ul></li> </ul><p><a href=„https://github.com/krzychb/esp-just-slip/blob/master/documents/just-slip-components-hws.jpg“ target=„_blank“><img src=„https://github.com/krzychb/esp-just-slip/raw/master/documents/just-slip-components-hws.jpg“ alt=„alt Sample configuration - components“/></a></p> <p>The following pins are used to connect particular modules:</p> <table><thead><tr><th>Module</th> <th>Pin Description</th> <th>Pin No.</th> <th><></th> <th>Pin No.</th> <th>Pin Description</th> <th>Module</th> </tr></thead><tbody><tr><td>ESP-01</td> <td>UART0 Rx</td> <td>GIPIO3</td> <td><></td> <td>TXD</td> <td>UART Tx</td> <td>Arduino</td> </tr><tr><td>ESP-01</td> <td>UART0 Tx</td> <td>GIPIO1</td> <td><></td> <td>RXD</td> <td>UART Rx</td> <td>Arduino</td> </tr><tr><td>ESP-01</td> <td>Ground</td> <td>GND</td> <td><></td> <td>GND</td> <td>Ground</td> <td>Arduino</td> </tr><tr><td>ESP-01</td> <td>UART1 Tx</td> <td>GPIO02</td> <td><></td> <td>Rx</td> <td>UART Rx</td> <td>USB-UART ESP</td> </tr><tr><td>ESP-01</td> <td>Ground</td> <td>GND</td> <td><></td> <td>GND</td> <td>Ground</td> <td>USB-UART ESP</td> </tr><tr><td>Arduino</td> <td>Soft UART Tx</td> <td>11</td> <td><></td> <td>Rx</td> <td>UART Rx</td> <td>USB-UART INO</td> </tr><tr><td>Arduino</td> <td>Soft UART Rx</td> <td>10</td> <td><></td> <td>Tx</td> <td>UART Tx</td> <td>USB-UART INO</td> </tr><tr><td>Arduino</td> <td>Reset</td> <td>RST</td> <td><></td> <td>DTR</td> <td>UART DTR</td> <td>USB-UART INO</td> </tr><tr><td>Arduino</td> <td>Power Supply</td> <td>RAW</td> <td><></td> <td>5V</td> <td>Power Supply</td> <td>ESP-01 PS</td> </tr><tr><td>Arduino</td> <td>Ground</td> <td>GND</td> <td><></td> <td>GND</td> <td>Ground</td> <td>USB-UART INO</td> </tr></tbody></table><p><a href=„https://github.com/krzychb/esp-just-slip/blob/master/documents/just-slip-connections-hws.jpg“ target=„_blank“><img src=„https://github.com/krzychb/esp-just-slip/raw/master/documents/just-slip-connections-hws.jpg“ alt=„alt Sample configuration - connections“/></a> Please refer to folder <a href=„https://github.com/krzychb/esp-just-slip/blob/master/documents“>documents</a> for additional pictures of connections.</p> <p>###Software Overview ESP8255 application should be compiled and loaded to module using provided make file. Use define in file <a href=„https://github.com/krzychb/esp-just-slip/blob/master/user/user_main.c“>user_main.c</a> to choose between SLIP over s/w or h/w serial.</p> <div class=„highlight highlight-source-c“><pre> comment define below if you would like to use Softuart #define USE_HW_SERIAL</pre></div> <p>Arduino should be loaded using <a href=„https://www.arduino.cc/en/Main/Software“>Arduino IDE</a>. There are two sketches for both s/w and h/w serial test scenarios available in the following folders:</p> <ul><li><a href=„https://github.com/krzychb/esp-just-slip/blob/master/ino-just-slip-sws“>ino-just-slip-sws</a> - SLIP over S/W Serial</li> <li><a href=„https://github.com/krzychb/esp-just-slip/blob/master/ino-just-slip-hws“>ino-just-slip-hws</a> - SLIP over H/W Serial</li> </ul><p>Functionally of those sketches is identical to the application loaded on ESP8266. There are some (slight) differences in code as Arduino sketches are written in C++ while ESP8266 application is written in pure C.</p> <p>Once applications are started the following information is displayed on <a href=„https://github.com/krzychb/esp-just-slip/blob/master/documents/just-slip-arduino-terminal.png“>Arduino Serial</a> and <a href=„https://github.com/krzychb/esp-just-slip/blob/master/documents/just-slip-esp8266-terminal.png“>ES8266 UART1</a> terminals:</p> <pre>… 4F 2E 00 00 AB E6 71 77 4E E0 76 D8 : 2% 50 2E 00 00 23 80 4D 60 3D B5 DA C8 : 2% 51 2E 00 00 51 3C 15 59 C6 E6 32 0E : 2% … </pre> <p>First four columns contain counter of packets received, next 8 bytes contain random data and last column contains percentage of packets lost or corrupt. Packets are sent every 30 ms at 57600 bps. Checking of UART input buffer for data is done every 10 ms.</p> <p>Basing on resuts of first test scenario (SLIP over s/w serial) on average 1% of packets received by Arduino are lost or corrupt. On ESP8266 side this value is below 0.5% (0% reported on terminal). The reason of bigger number of packet lost/corrupt on Arduino side is likely ESP8266 Wi-Fi routines that interrupt operation of SoftUART sending the packets. This is only a hypothesis that should be verified by specific testing.</p> <p>Packages lost or corrupt for second test scenario were 0% on both Arduino and ESP8266 side.</p> <p>The following s/w version have been used when developing and testing of esp-just-slip:</p> <ul><li><a href=„http://programs74.ru/udkew-en.html“>Unofficial Development Kit for Espressif ESP8266</a> v2.0.8 (esp_iot_sdk_v1.3.0_15_08_08)</li> <li><a href=„https://www.arduino.cc/en/Main/Software“>Arduino iDE 1.6.5</a></li> <li><a href=„https://www.arduino.cc/en/Reference/SoftwareSerial“>Arduino SoftwareSerial 1.0.0</a> - available through Arduino iDE > Sketch > Include Library > Manage Libraries</li> </ul><p>##Software API</p> <p>The following functions are implemented:</p> <div class=„highlight highlight-source-c“><pre>uint8_t ICACHE_FLASH_ATTR slipDecodeSerial(Softuart *softuart, uint8_t *dataBuffer); uint8_t ICACHE_FLASH_ATTR slipDecodeSerialUart0(uint8_t *dataBuffer); void ICACHE_FLASH_ATTR slipEncodeSerial(Softuart *softuart, uint8_t *dataBuffer, uint8_t nCount); void ICACHE_FLASH_ATTR slipEncodeSerialUart0(uint8_t *dataBuffer, uint8_t nCount); uint8_t ICACHE_FLASH_ATTR readKeyboard(uint8_t *dataBuffer); uint8_t ICACHE_FLASH_ATTR appendCrc16(uint8_t *dataBuffer, uint8_t nCount); bool ICACHE_FLASH_ATTR checkCrc16(uint8_t *dataBuffer, uint8_t nCount);</pre></div> <p>###Read and Decode Data</p> <div class=„highlight highlight-source-c“><pre> *softuart - pointer to software UART *dataBuffer - pointer to data buffer to store received data returned value - number of bytes read to dataBuffer uint8_t ICACHE_FLASH_ATTR slipDecodeSerial(Softuart *softuart, uint8_t *dataBuffer)</pre></div> <p>Read SLIP encoded data from software serial port, decode them and store in data buffer.</p> <div class=„highlight highlight-source-c“><pre> *dataBuffer - pointer to data buffer to store received data returned value - number of bytes read to dataBuffer uint8_t ICACHE_FLASH_ATTR slipDecodeSerialUart0(uint8_t *dataBuffer)</pre></div> <p>Read SLIP encoded data from UART0 serial port, decode them and store in data buffer.</p> <p>###Encode and Write Data</p> <div class=„highlight highlight-source-c“><pre> *softuart - pointer to software UART *dataBuffer - pointer to data buffer to read data from nCount - number of bytes to read form dataBuffer void ICACHE_FLASH_ATTR slipEncodeSerial(Softuart *softuart, uint8_t *dataBuffer, uint8_t nCount)</pre></div> <p>SLIP encode data taken from data buffer and send the over the software serial port.</p> <div class=„highlight highlight-source-c“><pre> *dataBuffer - pointer to data buffer to read data from nCount - number of bytes to read form dataBuffer void ICACHE_FLASH_ATTR slipEncodeSerialUart0(uint8_t *dataBuffer, uint8_t nCount)</pre></div> <p>SLIP encode data taken from data buffer and send the over the UART0 serial port.</p> <p>###Append CRC16 to Data</p> <div class=„highlight highlight-source-c“><pre> *dataBuffer - pointer to data buffer to calculate and append crc16 nCount - number of data bytes in dataBuffer returned value - number of bytes in data buffer including crc16 uint8_t ICACHE_FLASH_ATTR appendCrc16(uint8_t *dataBuffer, uint8_t nCount)</pre></div> <p>Calculate CRC16 for data contained in data buffer and append result to the end of data buffer</p> <p>###Check Data Integrity</p> <div class=„highlight highlight-source-c“><pre> *dataBuffer - pointer to data buffer nCount - number of data bytes in dataBuffer including crc16 returned value - true of false depending on result of crc16 check bool ICACHE_FLASH_ATTR checkCrc16(uint8_t *dataBuffer, uint8_t nCount)</pre></div> <p>Perform data integrity check by comparing CRC16 calculated for input data against CRC16 received.</p> <p>###Print Data Buffer</p> <div class=„highlight highlight-source-c“><pre> *dataBuffer - pointer to data buffer nCount - number of data bytes in dataBuffer including crc16 void ICACHE_FLASH_ATTR printBuffer(uint8_t *dataBuffer, uint8_t nCount)</pre></div> <p>Print values from dataBuffer for diagnostic purposes. The last two bytes of dataBuffer contain CRC16 and are not printed.</p> <p>##Acknowledgments</p> <p>Development of this esp-just-slip was done using the following resources:</p> <p>Thank you guys for your contribution to ESP8266 community. It is a great pleasure to work with applications you have developed.</p> <p>##Contributing</p> <p>Please report any <a href=„https://github.com/krzychb/esp-just-slip/issues“>issues</a> and submit <a href=„https://github.com/krzychb/esp-just-slip/pulls“>pull requests</a>. Feel free to contribute to the project in any way you like!</p> <p>##Author</p> <p>krzychb</p> <p>##Donations</p> <p>Invite me to freshly squeezed orange juice.</p> <p>##LICENSE - „MIT License“</p> <p>Copyright © 2015 krzychb</p> <p>Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the „Software“), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:</p> <p>The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.</p> <p>THE SOFTWARE IS PROVIDED „AS IS“, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</p> </article> </html>
Falls nicht anders bezeichnet, ist der Inhalt dieses Wikis unter der folgenden Lizenz veröffentlicht: CC Attribution-Noncommercial-Share Alike 4.0 International