Skip to content

Latest commit

 

History

History
649 lines (366 loc) · 32.5 KB

tcp-ip-networking.rst

File metadata and controls

649 lines (366 loc) · 32.5 KB
Raw

TCP/IP networking

This section describes the TCP/IP networking support in Circle. This covers initialization and configuration, the socket API, the available upper layer protocol clients and servers and a few utility classes. The TCP/IP networking support requires the scheduler in the system (see Multitasking).

The following sample programs demonstrate TCP/IP networking features:

Sample Desc ription
18-ntptime Sett ing the system time from a NTP server
20-tcpsimple TCP echo server
21-webserver Simple HTTP webserver
31-webclient Simple HTTP client (only for reference)
33-syslog Send

log messages to an UDP syslog server
35-mqttclient MQTT client
38-bootloader HTTP- and TFTP-based bootloader

CNetSubSystem

#include <circle/net/netsubsystem.h>

Note

Setting DeviceType to NetDeviceTypeWLAN is not enough to access a WLAN. Instead you have to instantiate and initialize the classes CBcm4343Device (WLAN hardware driver), CNetSubSystem and CWPASupplicant (support task for secure WLAN access) in this order. Please see the subsection WLAN support and the WLAN sample for details!

CNetConfig

#include <circle/net/netconfig.h>

CSocket

#include <circle/net/socket.h>
#include <circle/net/in.h>      // for IPPROTO_*, MSG_DONTWAIT
#include <circle/netdevice.h>       // for FRAME_BUFFER_SIZE

Note

Port numbers at the Circle socket API are in host byte order. This means you do not need to swap the byte order to network order, when you specify a little endian number to an API function.

Operations can be blocking or non-blocking. Blocking operations wait for the completion, before the function returns. Non-blocking operations return immediately, which means that you have to ensure on your own, that the system is not congested, e.g. if sending much data.

Clients

CDNSClient

#include <circle/net/dnsclient.h>

CHTTPClient

#include <circle/net/httpclient.h>
#include <circle/net/http.h>        // for THTTPStatus

Note

In the Internet of today there are only a few webservers any more, which provide plain HTTP access. For HTTPS (HTTP over TLS) access with Circle you can use the circle-stdlib project, which includes Circle as a submodule.

CNTPClient

#include <circle/net/ntpclient.h>

CNTPDaemon

#include <circle/net/ntpdaemon.h>

CMQTTClient

#include <circle/net/mqttclient.h>

Warning

This implementation does not support multi-byte-characters in strings.

enum TMQTTDisconnectReason
{
    MQTTDisconnectFromApplication           = 0,

    // CONNECT errors
    MQTTDisconnectUnacceptableProtocolVersion   = 1,
    MQTTDisconnectIdentifierRejected        = 2,
    MQTTDisconnectServerUnavailable         = 3,
    MQTTDisconnectBadUsernameOrPassword     = 4,
    MQTTDisconnectNotAuthorized         = 5,

    // additional errors
    MQTTDisconnectDNSError,
    MQTTDisconnectConnectFailed,
    MQTTDisconnectFromPeer,
    MQTTDisconnectInvalidPacket,
    MQTTDisconnectPacketIdentifier,
    MQTTDisconnectSubscribeError,
    MQTTDisconnectSendFailed,
    MQTTDisconnectPingFailed,
    MQTTDisconnectNotSupported,
    MQTTDisconnectInsufficientResources,

    MQTTDisconnectUnknown
};

CSysLogDaemon

#include <circle/net/syslogdaemon.h>

Servers

CHTTPDaemon

#include <circle/net/httpdaemon.h>
#include <circle/net/http.h>        // for THTTPStatus

Note

This class uses a listener/worker model. The initially created task listens for incoming requests (listener) and spawns a child task (worker), which processes the request and terminates afterwards.

class CMyWebServer : public CHTTPDaemon
{
public:
    CMyWebServer (CNetSubSystem *pNetSubSystem,
              CActLED       *pActLED,      // some user data
              CSocket       *pSocket = 0); // 0 for first instance

    CHTTPDaemon *CreateWorker (CNetSubSystem *pNetSubSystem,
                   CSocket   *pSocket);

    ...
};
#define MAX_CONTENT_SIZE    4000    // maximum content size of your pages

CMyWebServer::CMyWebServer (CNetSubSystem *pNetSubSystem,
                CActLED   *pActLED,
                CSocket   *pSocket)
:   CHTTPDaemon (pNetSubSystem, pSocket, MAX_CONTENT_SIZE),
    m_pActLED (pActLED)
{
}

CHTTPDaemon *CMyWebServer::CreateWorker (CNetSubSystem *pNetSubSystem,
                     CSocket       *pSocket)
{
    return new CMyWebServer (pNetSubSystem, m_pActLED, pSocket);
}

CTFTPDaemon

#include <circle/net/tftpdaemon.h>

Utilities

CIPAddress

#include <circle/net/ipaddress.h>

CMACAddress

#include <circle/macaddress.h>

Note

This class is belongs to the Circle base library, because it is needed there to implement non-USB network device drivers.

WLAN support

The WLAN support in Circle is based on three elements:

  1. Driver class :cppCBcm4343Device for the WLAN hardware
  2. TCP/IP networking subsystem, which is instantiated with the class :cppCNetSubSystem
  3. WPA Supplicant library, which is built from the submodule hostap, and is instantiated via the wrapper class :cppCWPASupplicant

To enable WLAN support in Circle, these elements have to be created and initialized in this order. This is demonstrated in the WLAN sample. The third element is only required to use secure WLAN networks.

Note

The TCP/IP networking subsystem must be configured to use the WLAN device (NetDeviceTypeWLAN) and must be initialized, without waiting for an IP address from the DHCP server (with the parameter FALSE). Because the DHCP protocol requires WPA Supplicant to work, :cppCNetSubSystem::Initialize() would never return otherwise.

CWPASupplicant

#include <wlan/hostap/wpa_supplicant/wpasupplicant.h>