Working with the networking stack

Legacy Networking Libraries

This documentation covers the networking libraries available for mbed OS 2. For mbed OS 5, the networking libraries have been revised to better support additional network stacks and thread safety here.

Getting Started

This is a simple example program. We asume there that your mbed is connected to the internet through an Ethernet network.

To get this first example running, you will need both EthernetNetIf and HTTPClient packages.

You can import these packages in the compiler as libraries using those links:

#include "mbed.h"
#include "EthernetNetIf.h"
#include "HTTPClient.h"

EthernetNetIf eth; 
HTTPClient http;
  
int main() {

  printf("Start\n");

  printf("\r\nSetting up...\r\n");
  EthernetErr ethErr = eth.setup();
  if(ethErr)
  {
    printf("Error %d in setup.\n", ethErr);
    return -1;
  }
  printf("\r\nSetup OK\r\n");
  
  HTTPText txt;
  
  HTTPResult r = http.get("http://mbed.org/media/uploads/donatien/hello.txt", &txt);
  if(r==HTTP_OK)
  {
    printf("Result :\"%s\"\n", txt.gets()); 
  }
  else
  {
    printf("Error %d\n", r);
  }
  
  while(1)
  {
  
  }
  
  return 0;
  
}

This program will basically retrieve the content of the "hello.txt" file and display it.

You can also import this program directly into the compiler: http://mbed.org/users/donatien/programs/HTTPClientExample

Stack architecture

Layering

The stack is ordered in three layers:

  • The interface layer provides network functionality to the stack through device-specific drivers. For instance, the Ethernet interface correspond to this layer.
  • The API exposes sockets to the top-level components. It abstracts the implementation from the user.
  • The high level modules contain all application-level protocol clients and servers, such as HTTP, NTP, etc.

Process

The stack is designed to run cooperatively with other services in a monothreaded environment. To achieve that some time-critical routines are executed in interrupt context, but most of the code is called in user context.

To function properly the stack must be polled at a regular interval. The static method Net::poll() ensures that every component of the stack keeps running. So you don't need to care about which module you have to poll or not.

To be able to work cooperatively in a single-threaded environment, the stack uses an event/callback model. Most methods are non blocking and raise an event on completion.

However, to keep things simple, some top-level components (such as the HTTP Client) expose as well an equivalent blocking function that returns on completion (basically it just calls Net::poll() for you ;)).

Packaging

The stack is split into two kinds of packages, of which you can get both the source or a precompiled version:

  • The Services packages contain the high level modules of the stack (eg. HTTPClient)
  • The Interface+API packages (eg. Ethernet+API = EthernetNetIf) are specific to a particular interface and contain the API layer as well for ease of use