or

QNEthernet, an lwIP-Based Ethernet Library For Teensy 4.1 and other platforms

Version: 0.36.0-snapshot

The QNEthernet library provides Ethernet functionality for the Teensy 4.1 and possibly some other platforms. It's designed to be compatible with the Arduino-style Ethernet API.

This library is distributed under the "AGPL-3.0-or-later" license. Please contact the author if you wish to inquire about other license options.

Please see the lwip-info/ directory for the info files provided with the lwIP release.

Table of contents

1. Introduction
   1. Three notes
   2. Other differences and notes
   3. Requirements
2. Additional functions and features not in the Arduino-style API
   1. Ethernet
   2. EthernetClient
      1. TCP socket options
      2. IP header values
   3. EthernetServer
   4. EthernetUDP
      1. IP header values
      2. parsePacket() return values
   5. EthernetFrame
   6. MDNS
   7. DNSClient
   8. Ping
      1. Ping reply
   9. Print and Stream utilities
   10. operator bool() and explicit
   11. Use of errno
3. How to run
   1. Concurrent use is not supported
   2. How to move the stack forward and receive data
   3. Link detection
   4. Notes on yield()
4. How to write data to connections
   1. writeFully() with more break conditions
   2. Write immediacy
5. A note on the examples
6. A survey of how connections (aka EthernetClient) work
   1. Connections and link/interface detection
   2. connect() behaviour and its return values
   3. Non-blocking connection functions
   4. Getting the TCP state
7. How to use multicast
8. How to use listeners
9. How to change the number of sockets
10. UDP receive buffering
11. mDNS services
12. DNS
13. stdio
    1. Adapt stdio files to the Print interface
14. Raw Ethernet frames
    1. Promiscuous mode
    2. Raw frame receive buffering
    3. Raw frame loopback
15. How to implement VLAN tagging
16. Application layered TCP: TLS, proxies, etc.
    1. About the allocator functions
    2. About the TLS adapter functions
    3. How to enable Mbed TLS
       1. Installing the Mbed TLS library
          1. Mbed TLS library install for Arduino IDE
          2. Mbed TLS library install for PlatformIO
       2. Implementing the altcp_tls_adapter functions
       3. Implementing the Mbed TLS entropy function
17. On connections that hang around after cable disconnect
    1. Mitigations
18. Notes on ordering and timing
19. Notes on RAM1 usage (Teensy 4)
20. Heap memory use
21. Entropy generation
    1. The RandomDevice UniformRandomBitGenerator
22. Interference mitigation
23. Security features
    1. Secure TCP initial sequence numbers (ISNs)
    2. Disabling ICMP echo (ping) replies
24. Configuration macros
    1. Configuring macros using the Arduino IDE
    2. Configuring macros using PlatformIO
    3. Changing lwIP configuration macros in lwipopts.h
25. Auxiliary tools
    1. Print and Stream tools
    2. std::random_device-compatible uniform random bit generator
    3. Space-savings on some platforms
    4. std::chrono-compatible Clocks
       1. steady_clock_ms
       2. arm_high_resolution_clock
       3. elapsedTime<Clock>
26. Complete list of features
27. Compatibility with other APIs
28. Other notes
29. To do
30. Code style
31. References

Introduction

The QNEthernet library is designed to be a drop-in replacement for code using the Arduino-style Ethernet API.

Note: Please read the function docs in the relevant header files for more information.

Three notes

There are three notes, as follows:

1. The QNEthernet.h header must be included instead of Ethernet.h.
2. Everything is inside the qindesign::network namespace. In many cases, adding the following at the top of your program will obviate the need to qualify any object uses or make any other changes:

   using namespace qindesign::network;
   

3. On non-Teensy platforms: Ethernet.loop() must be called regularly, either at the end of the main loop() function, or by hooking into yield(). (This is already done for you on the Teensy platform by hooking into yield() via EventResponder.)
   See: How to move the stack forward and receive data

For API additions beyond what the Arduino-style API provides, see:
Additional functions and features not in the Arduino-style API

Other differences and notes

• UDP support is already included in QNEthernet.h. There's no need to also include QNEthernetUDP.h.
• Ethernet loop() is called from yield() (automatically on the Teensy platform). The functions that wait for timeouts rely on this. This also means that you must use delay(ms) (assuming it internally calls yield()), yield(), or Ethernet.loop() when waiting on conditions; waiting without calling these functions will cause the TCP/IP stack to never refresh. Note that many of the I/O functions call loop() so that there's less burden on the calling code.
• All but one of the Ethernet.begin(...) functions don't block. Ethernet.begin(mac[, timeout]) blocks, while waiting for an IP address, to match the Arduino-style API. It uses a default timeout of 60 seconds. This behaviour can be emulated by following a call to begin() with a loop that checks Ethernet.localIP() for a valid IP. See also the new Ethernet.waitForLocalIP(timeout) or Ethernet.onAddressChanged(cb).
• The Arduino-style Ethernet.begin(mac, ...) functions all accept a NULL MAC address. If the address is NULL then the internal or system default MAC address will be used. As well, if Ethernet fails to start then the MAC address will not be changed.
• EthernetServer::write(...) functions always return the write size requested. This is because different clients may behave differently.
• The examples at server.accept() and if (EthernetClient) directly contradict each other with regard to what operator bool() means in EthernetClient. The first example uses it as "already connected", while the second uses it as "available to connect". "Connected" is the chosen concept, but different from connected() in that it doesn't check for unread data.
• The three Arduino-defined Ethernet.begin(...) functions that use the MAC address and that don't specify a subnet are deprecated because they make some incorrect assumptions about the subnet and gateway.
• Ethernet.hardwareStatus(): Adds EthernetOtherHardware and EthernetTeensy41 to the list of possible return values. Note that these values are not defined in the Arduino-style API.
• The following Ethernet functions are deprecated and do nothing or return some default value:
  • maintain(): Returns zero.
  • setRetransmissionCount(uint8_t number): Does nothing.
  • `setRet