Nicolas Nackel / Mbed 2 deprecated PPP-Blinky

Small Internet Protocol Stack using a standard serial port.

Dependencies:   mbed

PPP-Blinky - TCP/IP Networking Over a Serial Port

Note: The source code is at the bottom of this page.

/media/uploads/nixnax/blinky-connected.gif
A Windows desktop showing PPP-Blinky in the network connections list.

Describe PPP-Blinky in Three Sentences

PPP-Blinky is a tiny library that enables Internet protocols (IPv4) to any mbed target hardware by using only a serial port.

The code runs on processors with as little as 8k RAM, for example the Nucleo-L053R8 board.

PPP-Blinky uses the industry-standard PPP (Point-to-Point) Protocol and a tiny "stateless" TCP/IP stack.

No Ethernet Port Required

No ethernet port is required - PPP-Blinky uses a serial port to send IP packets to your PC.

PPP-Blinky emulates a standard dial-up modem and therefore connects to Windows, Linux or Adroid machines.

The code runs on most ARM mbed platforms such as the LPC11U24 shown in the picture below:

/media/uploads/nixnax/blinky-to-laptop1.jpg mbed LPC11u24 acting as a webserver to a Windows laptop.

Webserver

The Webserver and WebSocket functions are ideal for building browser-based GUIs on mbed-enabled hardware.

PPP-Blinky's HTTP webserver works with most web clients such as Internet Explorer, Mozilla Firefox, Google Chrome, Safari, Curl, wget and Lynx as well as Microsoft Powershell Invoke-Webrequest command.

In the image below Firefox web browser displays the main web page embedded into PPP-Blinky's code:

/media/uploads/nixnax/ppp-blinky-firefox.jpg Firefox web browser displays a web page embedded into PPP-Blinky's code

WebSocket Service

WebSocket is the most popular protocol standard for real-time bidirectional TCP/IP communication between clients and servers.
In the image below a small Internet Explorer script has connected to PPP-Blinky's WebSocket Service.
A websocket message was then sent by the browser and was echoed back by the WebSocket, triggering the onmessage event in the script.
The WebSocket service enables bidirectional real-time interaction between PPP-Blinky and any element in the browser DOM via JavaScript.
If you already have PPP-Blinky up and running you can test your WebSocket service using this: http://jsfiddle.net/d26cyuh2/112/embedded/result
Websockets are ideal for building browser-based GUIs for mbed hardware.

/media/uploads/nixnax/ppp-blinky-websocke-2.gif

Trying PPP-Blinky on your mbed board

You will need an mbed-enabled hardware board: https://developer.mbed.org/platforms/

Establish a serial port connection between your host PC and your mbed board. The easiest way is to use mbed hardware with a USB serial debug port. I've tried the ST-Micro Nucleo-L476RG, Nucleo-L152RE, Nucleo-F401RE, Nucleo-L432KC, Nucleo-L053R8, mbed-LPC11U24 and mbed-LPC1768 boards and they all work out of the box. Use the mbed online compiler to compile the software for your target board. Save the compiled binary to your hardware.

Before establishing a network connection, you can verify the operation of the code by opening a terminal program such as Tera Term, and setting the baud rate of the COM port on your mbed board to 115200 baud. LED1 should toggle for every two 0x7E (~) (i.e. tilde) characters you type, as 0x7E is the PPP frame start/end marker. Don't forget to close the port when your'e done testing, or else Windows Dial-up Networking will report that the COM port is in use by another program when you try to connect.

Once you are certain that the serial port and firmware is working, proceed to creating a new network connection on your PC -see below.

Creating a Dial-up Connection in Windows

/media/uploads/nixnax/modem.jpg

Setting up Dial-Up Networking (DUN) on your Windows 7 or 8 PC is essentially a two-step process: First, you create a new modem device, because PPP-blinky partially emulates a standard Windows serial port modem device. Second, you create a new Internet connection (in practice, a new network adapter) which is associated with your new "modem".

Step-by-step description of how to configure Windows for PPP-Blinky here:

/users/nixnax/code/PPP-Blinky/wiki/Configuring-Windows-Dial-Up-Networking

There is also a screen on how to set up Linux dial-up networking near the bottom of this page.

Connecting to PPP-Blinky from your PC

Once Windows networking is configured you can establish a dial-up connection to your mbed board over the USB virtual com port.

The IP address you manually assigned to the new dial-up network adapter (172.10.10.1) functions as a gateway to any valid IP address on that subnet. In the screen capture below, I'm sending pings from the Windows 8 command line to my ST-Micro Nucleo-L476RG board over the USB virtual serial Port. I'm also using a second serial port and Tera Term to capture the debug output from a second serial port on the hardware. The optional debug output from the board prints out the IP source and destination address and the first few bytes of the data payload. Note that the source is the adapter IP address, (172.10.10.1 in this case) and the destination is some other address on that subnet - all packets to the subnet are sent to our mbed hardware. For example, you could also ping 172.10.10.123 or, if your PPP-Blinky is running, simply click on this link: http://172.10.10.123

/media/uploads/nixnax/ping-cap-3.gif

One Million Pings!

In the image below the ICMP ("ping") echo reply service was tested by sending one million pings to ppp-Blinky. This took over two hours.
The ping tool used on the Windows 8 PC was psping.exe from PsTools by Mark Russinovich - http://bit.ly/PingFast
The average reply time for a short ping (1 byte of payload data) was 11 milliseconds at 115200 baud on the $10 Nucleo-L053R8 board - barely enough time for 130 bytes to be sent over the port!

/media/uploads/nixnax/ppp-blinky-ping-results.jpg

Monitoring PPP-Blinky Packets

The image below is from a Microsoft Network Monitor 3.4 capture session.

Responses from PPP-Blinky are shown in blue.

Frame 2 - Internet Explorer at IP 172.10.10.1 (the Dial-Up Adapter IP) requests a TCP connection by sending an S (SYN) flag.
Frame 3 - PPP-Blinky at IP 172.10.10.2 responds with an ACK in frame 3. One direction of the link is now established.
Frame 4 - The PC acknowledges the SYN sent by PPP-Blinky in frame 3. The TCP link is now fully established.
Frame 5 - The browser "pushes" (P flag is set) an HTTP GET request to PPP-Blinky.
Frame 6 - PPP-Blinky responds with a standard HTTP response "pushes" (P flag set) back a small web page. It also sets the A (ACK) flag to acknowledge the message sent in frame 6.
Frame 7 - The PC acknowledges reception of the HTTP payload.
Frame 8 - The PC starts to shut down the TCP connection by sending a FIN flag.
Frame 9 - PPP-Blinky acknowledges the FIN request - the connection is now closed in one direction. It also sets a FIN flag in the response to request closure of the opposite direction of the connection.
Frame 10 - The PC acknowledges the FIN request. The closing of the TCP connection is now confirmed in both directions.

/media/uploads/nixnax/ms-network-monitor-http-get-1.gif

Debug Output

PPP-Blinky can output handy debug information to an optional second serial port.
The image below shows the debug output (Ident, Source, Destination, TCP Flags) for a complete HTTP conversation.
The PC messages are displayed in black. PPP-Blinky messages are blue.
Notice how PPP-blinky automatically inserts a blank line after each full HTTP conversation.

/media/uploads/nixnax/tcp-data-3.gif

Creating a Dial-Up Connection in Linux

The screen below shows the required pppd command to connect to PPP-Blinky from a Linux machine. This was much simpler than Windows! The USB serial port of the mbed LPC1768 board registered as /dev/ttyACM0 on my Linux box. Do a websearch on pppd if you want to learn more about pppd, the Linux PPP handler. Near the bottom of the screen below, two webpages are fetched (/ and /y) by using the curl command on the command line. Gnome Webkit and Firefox work fine, too. Also try echo GET / HTTP/1.1 | nc 172.10.10.2 which uses netcat, the "Swiss army knife" of networking tools. PPP-Blinky was also tested with ApacheBench, the Apache server benchmark software. After 100000 fetches, the mean page fetch rate was reported as 6 page fetches per second for a small page.

/media/uploads/nixnax/pppd-screen.png

Caveats

PPP Blinky is an extremely sparse implementation (1.5k lines) of HTTP,WebSocket,TCP, UDP, ICMP, IPCP and LCP over PPP, requiring around 8kB of RAM. The minimum functionality required to establish connectivity is implemented. These are often acceptable tradeoffs for embedded projects as well as a handy tool to learn the practical details of everyday networking implementations.

PPP-Blinky/ppp-blinky.h@253:ee1044976b2c, 2019-01-17 (annotated)

Committer:
nixnax
Date:
Thu Jan 17 16:13:36 2019 +0000
Revision:
253:ee1044976b2c
Parent:
244:f062ca9b6e06
Child:
262:c044fed611aa
PPP frames were double-counted.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
nixnax 142:54d1543e23e5 1 /// ppp-blinky.h
nixnax 142:54d1543e23e5 2
nixnax 142:54d1543e23e5 3 #include "mbed.h"
nixnax 142:54d1543e23e5 4 #include "sha1.h"
nixnax 142:54d1543e23e5 5
nixnax 144:01d98cf7738e 6 void initializePpp();
nixnax 150:3366bf3d294e 7 int connectedPpp();
nixnax 153:7993def8663f 8 void waitForPcConnectString();
nixnax 142:54d1543e23e5 9 void waitForPppFrame();
nixnax 152:025c73b6c0a9 10 void determinePacketType();
nixnax 174:e5a3f16421a5 11 void sendUdpData();
nixnax 152:025c73b6c0a9 12
nixnax 159:4d1bf96a59cd 13 /// PPP header
nixnax 153:7993def8663f 14 typedef struct { // [ff 03 00 21]
nixnax 167:ff8a2d8beeb1 15 unsigned int address : 8; // always 0xff
nixnax 167:ff8a2d8beeb1 16 unsigned int control : 8; // always 03
nixnax 167:ff8a2d8beeb1 17 unsigned int protocolR : 16; // byte reversed, 0x0021 for ip
nixnax 152:025c73b6c0a9 18 } pppHeaderType;
nixnax 152:025c73b6c0a9 19
nixnax 167:ff8a2d8beeb1 20 /// LCP and IPCP header
nixnax 167:ff8a2d8beeb1 21 typedef struct {
nixnax 167:ff8a2d8beeb1 22 // ppp part
nixnax 167:ff8a2d8beeb1 23 unsigned int address : 8; // always 0xff
nixnax 167:ff8a2d8beeb1 24 unsigned int control : 8; // always 03
nixnax 167:ff8a2d8beeb1 25 unsigned int protocolR : 16; // byte reversed, 0x0021 for ip
nixnax 167:ff8a2d8beeb1 26
nixnax 167:ff8a2d8beeb1 27 // ipcp and lcp part
nixnax 167:ff8a2d8beeb1 28 unsigned int code : 8; // IPCP and LCP contain a code field which identifies the requested action or response
nixnax 167:ff8a2d8beeb1 29 unsigned int identifier : 8 ;
nixnax 167:ff8a2d8beeb1 30 unsigned int lengthR : 16;
nixnax 173:6774a0c851c4 31 char request [0];
nixnax 167:ff8a2d8beeb1 32 } ipcpHeaderType;
nixnax 167:ff8a2d8beeb1 33
nixnax 159:4d1bf96a59cd 34 /// IP header
nixnax 152:025c73b6c0a9 35 typedef struct {
nixnax 154:18b2bd92f557 36 unsigned int headerLength : 4; // ip headerlength / 4
nixnax 154:18b2bd92f557 37 unsigned int version : 4; // ip version number
nixnax 154:18b2bd92f557 38 unsigned int ect : 1; // ecn capable transport
nixnax 154:18b2bd92f557 39 unsigned int ce : 1; // ecn-ce
nixnax 154:18b2bd92f557 40 unsigned int dscp : 6; // differentiated services
nixnax 160:bd701ad564cb 41 unsigned int lengthR : 16; // ip packet length (byte-reversed)
nixnax 167:ff8a2d8beeb1 42
nixnax 160:bd701ad564cb 43 unsigned int identR : 16; // ident, byte reversed
nixnax 160:bd701ad564cb 44 unsigned int fragmentOffsHi : 5;
nixnax 154:18b2bd92f557 45 unsigned int lastFragment : 1;
nixnax 160:bd701ad564cb 46 unsigned int dontFragment : 1;
nixnax 160:bd701ad564cb 47 unsigned int reservedIP : 1;
nixnax 160:bd701ad564cb 48 unsigned int fragmentOffsLo : 8;
nixnax 167:ff8a2d8beeb1 49
nixnax 160:bd701ad564cb 50 unsigned int ttl : 8;
nixnax 154:18b2bd92f557 51 unsigned int protocol : 8; // next protocol
nixnax 161:d59f778bc8ab 52 unsigned int checksumR : 16; // ip checksum, byte reversed
nixnax 167:ff8a2d8beeb1 53 union {
nixnax 167:ff8a2d8beeb1 54 unsigned int srcAdrR; // source IP address
nixnax 167:ff8a2d8beeb1 55 char srcAdrPtr [0]; // so we also have a char * to srcAdrR
nixnax 167:ff8a2d8beeb1 56 };
nixnax 167:ff8a2d8beeb1 57 union {
nixnax 167:ff8a2d8beeb1 58 unsigned int dstAdrR; // destination IP address
nixnax 167:ff8a2d8beeb1 59 char dstAdrPtr [0]; // so we also have a char * to dstAdrR
nixnax 167:ff8a2d8beeb1 60 };
nixnax 152:025c73b6c0a9 61 } ipHeaderType;
nixnax 152:025c73b6c0a9 62
nixnax 164:c3de3d212c4b 63 /// IP pseudoheader. Used in TCP/UDP checksum calculations.
nixnax 152:025c73b6c0a9 64 typedef struct {
nixnax 159:4d1bf96a59cd 65 union {
nixnax 167:ff8a2d8beeb1 66 char start [0]; // a char * to avoid type conversions
nixnax 160:bd701ad564cb 67 unsigned int srcAdrR; // source IP address
nixnax 159:4d1bf96a59cd 68 };
nixnax 159:4d1bf96a59cd 69 unsigned int dstAdrR; // destination IP address
nixnax 159:4d1bf96a59cd 70 unsigned int zero : 8;
nixnax 159:4d1bf96a59cd 71 unsigned int protocol : 8;
nixnax 159:4d1bf96a59cd 72 unsigned int lengthR : 16; // byte reversed
nixnax 159:4d1bf96a59cd 73 } pseudoIpHeaderType;
nixnax 159:4d1bf96a59cd 74
nixnax 159:4d1bf96a59cd 75 /// TCP header
nixnax 159:4d1bf96a59cd 76 typedef struct {
nixnax 159:4d1bf96a59cd 77 unsigned int srcPortR : 16; // byte reversed
nixnax 159:4d1bf96a59cd 78 unsigned int dstPortR : 16; // byte reversed
nixnax 155:9c6a1d249e26 79 unsigned int seqTcpR; // byte reversed
nixnax 155:9c6a1d249e26 80 unsigned int ackTcpR; // byte reversed
nixnax 156:163c23249731 81 unsigned int resvd1 : 4; // reserved
nixnax 156:163c23249731 82 unsigned int offset : 4; // tcp header length [5..15]
nixnax 152:025c73b6c0a9 83 union {
nixnax 156:163c23249731 84 unsigned char All; // all 8 flag bits
nixnax 156:163c23249731 85 struct { // individual flag bits
nixnax 156:163c23249731 86 unsigned char fin: 1, // fin
nixnax 156:163c23249731 87 syn : 1, // syn
nixnax 156:163c23249731 88 rst : 1, // rst
nixnax 156:163c23249731 89 psh : 1, // psh
nixnax 156:163c23249731 90 ack : 1, // ack
nixnax 156:163c23249731 91 urg : 1, // urg
nixnax 156:163c23249731 92 ece : 1, // ece
nixnax 156:163c23249731 93 cwr : 1; // cwr
nixnax 152:025c73b6c0a9 94 };
nixnax 156:163c23249731 95 } flag;
nixnax 156:163c23249731 96 unsigned int windowR : 16; // byte reversed
nixnax 154:18b2bd92f557 97 unsigned int checksumR : 16; // byte reversed
nixnax 154:18b2bd92f557 98 unsigned int urgentPointerR : 16; // byte reversed;
nixnax 154:18b2bd92f557 99 unsigned int tcpOptions[10]; // up to 10 words of options possible
nixnax 154:18b2bd92f557 100 } tcpHeaderType;
nixnax 159:4d1bf96a59cd 101
nixnax 164:c3de3d212c4b 102 /// UDP header.
nixnax 163:d1b4328e9f08 103 typedef struct {
nixnax 164:c3de3d212c4b 104 unsigned int srcPortR : 16; // byte reversed
nixnax 164:c3de3d212c4b 105 unsigned int dstPortR : 16; // byte reversed
nixnax 164:c3de3d212c4b 106 unsigned int lengthR : 16; // byte reversed
nixnax 170:3d3b2126181c 107 unsigned int checksumR : 16; // byte reversed
nixnax 163:d1b4328e9f08 108 char data [0]; // data area
nixnax 163:d1b4328e9f08 109 } udpHeaderType;
nixnax 165:c47826d07e0d 110
nixnax 165:c47826d07e0d 111 /// ICMP header.
nixnax 165:c47826d07e0d 112 typedef struct {
nixnax 165:c47826d07e0d 113 unsigned int type : 8;
nixnax 165:c47826d07e0d 114 unsigned int code : 8;
nixnax 165:c47826d07e0d 115 unsigned int checkSumR : 16; // byte reversed
nixnax 165:c47826d07e0d 116 unsigned int idR : 16; // byte reversed
nixnax 165:c47826d07e0d 117 unsigned int sequenceR : 16; // byte reversed
nixnax 165:c47826d07e0d 118 char data [0]; // data area
nixnax 165:c47826d07e0d 119 } icmpHeaderType;
nixnax 175:b4e6f8a6fe00 120
nixnax 175:b4e6f8a6fe00 121 /// Structure to manage all ppp variables.
nixnax 175:b4e6f8a6fe00 122 typedef struct pppType {
nixnax 175:b4e6f8a6fe00 123 union {
nixnax 175:b4e6f8a6fe00 124 pppHeaderType * ppp; // pointer to ppp structure
nixnax 175:b4e6f8a6fe00 125 ipcpHeaderType * ipcp; // pointer to ipcp structure
nixnax 175:b4e6f8a6fe00 126 ipcpHeaderType * lcp; // pointer to lcp structure (same as ipcp)
nixnax 175:b4e6f8a6fe00 127 };
nixnax 175:b4e6f8a6fe00 128 union {
nixnax 175:b4e6f8a6fe00 129 ipHeaderType * ip; // pointer to ip header struct
nixnax 175:b4e6f8a6fe00 130 char * ipStart; // char pointer to ip header struct (need a char pointer for byte offset calculations)
nixnax 175:b4e6f8a6fe00 131 };
nixnax 175:b4e6f8a6fe00 132 union { // a union for the packet type contained in the IP packet
nixnax 175:b4e6f8a6fe00 133 tcpHeaderType * tcp; // pointer to tcp header struct
nixnax 175:b4e6f8a6fe00 134 udpHeaderType * udp; // pointer to udp header struct
nixnax 175:b4e6f8a6fe00 135 icmpHeaderType * icmp; // pointer to udp header struct
nixnax 175:b4e6f8a6fe00 136 char * tcpStart; // char pointer to tcp header struct (need a char pointer for byte offset calculations)
nixnax 175:b4e6f8a6fe00 137 char * udpStart; // char pointer to udp header struct (need a char pointer for byte offset calculations)
nixnax 175:b4e6f8a6fe00 138 char * icmpStart; // char pointer to icmp header struct (need a char pointer for byte offset calculations)
nixnax 175:b4e6f8a6fe00 139 };
nixnax 175:b4e6f8a6fe00 140 char * tcpData; // char pointer to where tcp data starts
nixnax 212:a9646f0a8c46 141 volatile int online; // we hunt for a PPP connection if this is zero
nixnax 175:b4e6f8a6fe00 142 int hostIP; // ip address of host
nixnax 175:b4e6f8a6fe00 143 int fcs; // PPP "frame check sequence" - a 16-bit HDLC-like checksum used in all PPP frames
nixnax 175:b4e6f8a6fe00 144 int ledState; // state of LED1
nixnax 175:b4e6f8a6fe00 145 int responseCounter;
nixnax 241:dece92cb7296 146 unsigned int pingCount; // counts how many times we get an ICMP ping packet
nixnax 175:b4e6f8a6fe00 147 int firstFrame; // cleared after first frame
nixnax 175:b4e6f8a6fe00 148 unsigned int sum; // a checksum used in headers
nixnax 175:b4e6f8a6fe00 149 struct {
nixnax 244:f062ca9b6e06 150 #define RXBUFLEN 4000
nixnax 226:4898247048c7 151 // the serial port receive buffer and packet buffer, size is RXBUFLEN
nixnax 226:4898247048c7 152 // TODO - not sure why this buffer has to be this big
nixnax 223:917b554cb8a5 153 volatile char buf[RXBUFLEN+1];
nixnax 181:bcfe7fe2142d 154 volatile int head; // declared volatile so user code knows this variable changes in the interrupt handler
nixnax 212:a9646f0a8c46 155 volatile int tail;
nixnax 212:a9646f0a8c46 156 volatile int rtail;
nixnax 211:a40c58b34560 157 volatile int buflevel; // how full the buffer is
nixnax 212:a9646f0a8c46 158 volatile int maxbuflevel; // maximum value that buflevel ever got to
nixnax 221:1d7c32d8256b 159 volatile int bufferfull; // flag when buffer is full
nixnax 175:b4e6f8a6fe00 160 } rx; // serial port objects
nixnax 175:b4e6f8a6fe00 161 struct {
nixnax 175:b4e6f8a6fe00 162 int len; // number of bytes in buffer
nixnax 175:b4e6f8a6fe00 163 int crc; // PPP CRC (frame check)
nixnax 226:4898247048c7 164 #define PPP_max_size 1600
nixnax 226:4898247048c7 165 // we are assuming 100 bytes more than MTU size of 1500
nixnax 175:b4e6f8a6fe00 166 char buf[PPP_max_size]; // send and receive buffer large enough for largest IP packet
nixnax 175:b4e6f8a6fe00 167 } pkt; // ppp buffer objects
nixnax 175:b4e6f8a6fe00 168 struct {
nixnax 175:b4e6f8a6fe00 169 int frameStartIndex; // frame start marker
nixnax 175:b4e6f8a6fe00 170 int frameEndIndex; // frame end marker
nixnax 175:b4e6f8a6fe00 171 } hdlc; // hdlc frame objects
nixnax 175:b4e6f8a6fe00 172 struct {
nixnax 175:b4e6f8a6fe00 173 unsigned int ident; // our IP ident value (outgoing frame count)
nixnax 175:b4e6f8a6fe00 174 } ipData; // ip related object
nixnax 175:b4e6f8a6fe00 175 } pppVariables;
nixnax 175:b4e6f8a6fe00 176