Skip to content
This repository has been archived by the owner on Jan 29, 2023. It is now read-only.

Asynchronous TCP Library for Teensy 4.1 using QNEthernet. This library is the base for future Async support for many current or future libraries, such as AsyncHTTPRequest_Generic, AsyncHTTPSRequest_Generic, AsyncMQTT_Generic, AsyncWebServer_Teensy41, AsyncUDP_Teensy41, AsyncDNSServer_Teensy41, AsyncTCP_SSL_Teensy41, etc.

License

Notifications You must be signed in to change notification settings

khoih-prog/Teensy41_AsyncTCP

Repository files navigation

Teensy41_AsyncTCP

arduino-library-badge GitHub release contributions welcome GitHub issues

Donate to my libraries using BuyMeACoffee



Table of contents



Why do we need this Teensy41_AsyncTCP library

Features

This library is based on, modified from:

  1. Hristo Gochkov's ESPAsyncTCP
  2. Hristo Gochkov's AsyncTCP

to apply the better and faster asynchronous feature of the powerful ESPAsyncTCP Library without SSL to Teensy 4.1 using LwIP-based QNEthernet Library, and will be the base for future or current and more advanced Async libraries, such as AsyncHTTPRequest_Generic, AsyncHTTPRequest_Generic, AsyncMQTT_Generic, AsyncWebServer_Teensy41, AsyncUDP_Teensy41, AsyncDNSServer_Teensy41, AsyncTCP_SSL_Teensy41, etc.

Why Async is better

  • Using asynchronous network means that you can handle more than one connection at the same time
  • You are called once the request is ready and parsed
  • When you send the response, you are immediately ready to handle other connections while the server is taking care of sending the response in the background
  • Speed is OMG
  • Easy to use API, HTTP Basic and Digest MD5 Authentication (default), ChunkedResponse
  • Easily extensible to handle any type of content
  • Supports Continue 100
  • Async WebSocket plugin offering different locations without extra servers or ports
  • Async EventSource (Server-Sent Events) plugin to send events to the browser
  • URL Rewrite plugin for conditional and permanent url rewrites
  • ServeStatic plugin that supports cache, Last-Modified, default index and more
  • Simple template processing engine to handle templates

Currently supported Boards

  1. Teensy 4.1 using QNEthernet Library


Prerequisites

  1. Arduino IDE 1.8.19+ for Arduino. GitHub release
  2. Teensy core v1.57+ for Teensy 4.1
  3. QNEthernet Library version v0.16.0+ for Teensy 4.1 built-in Ethernet.


Installation

Use Arduino Library Manager

The best and easiest way is to use Arduino Library Manager. Search for Teensy41_AsyncTCP, then select / install the latest version. You can also use this link arduino-library-badge for more detailed instructions.

Manual Install

Another way to install is to:

  1. Navigate to Teensy41_AsyncTCP page.
  2. Download the latest release Teensy41_AsyncTCP-main.zip.
  3. Extract the zip file to Teensy41_AsyncTCP-main directory
  4. Copy whole Teensy41_AsyncTCP-main folder to Arduino libraries' directory such as ~/Arduino/libraries/.

VS Code & PlatformIO

  1. Install VS Code
  2. Install PlatformIO
  3. Install Teensy41_AsyncTCP library by using Library Manager. Search for Teensy41_AsyncTCP in Platform.io Author's Libraries
  4. Use included platformio.ini file from examples to ensure that all dependent libraries will installed automatically. Please visit documentation for the other options and examples at Project Configuration File


HOWTO Fix Multiple Definitions Linker Error

The current library implementation, using xyz-Impl.h instead of standard xyz.cpp, possibly creates certain Multiple Definitions Linker error in certain use cases.

You can include this .hpp file

// Can be included as many times as necessary, without `Multiple Definitions` Linker Error
#include "Teensy41_AsyncTCP.hpp"     //https://github.com/khoih-prog/Teensy41_AsyncTCP

in many files. But be sure to use the following .h file in just 1 .h, .cpp or .ino file, which must not be included in any other file, to avoid Multiple Definitions Linker Error

// To be included only in main(), .ino with setup() to avoid `Multiple Definitions` Linker Error
#include "Teensy41_AsyncTCP.h"       //https://github.com/khoih-prog/Teensy41_AsyncTCP

Check the new multiFileProject example for a HOWTO demo.



Original documentation

Check AsyncTCP Library

This is a fully asynchronous TCP library, aimed at enabling trouble-free, multi-connection network environment for Teensy 4.1 using QNEthernet Library.

AsyncClient and AsyncServer

The base classes on which everything else is built. They expose all possible scenarios, but are really raw and require more skills to use.

AsyncPrinter

This class can be used to send data like any other Print interface (Serial for example).

The object then can be used outside of the Async callbacks (the loop) and receive asynchronously data using onData. The object can be checked if the underlying AsyncClientis connected, or hook to the onDisconnect callback.

AsyncTCPbuffer

This class is really similar to the AsyncPrinter, but it can buffer some of the incoming data.

SyncClient

It is exactly what it sounds like. This is a standard, synchronous blocking TCP Client you're used to.



Libraries currently depend on this library

  1. AsyncWebServer_Teensy41 GitHub release
  2. AsyncHTTPRequest_Teensy41 GitHub release
  3. AsyncMQTT_Generic GitHub release


Examples

  1. multiFileProject.


Debug Terminal Output Samples

1. FullyFeatured_QNEthernet on TEENSY 4.1 using DHCP

Following is the debug terminal when running example FullyFeatured_QNEthernet on Teensy 4.1 using QNEthernet Library to demonstrate the operation of Async MQTT request, relied on Teensy41_AsyncTCP Library

Starting FullyFeatured_QNEthernet on TEENSY 4.1
AsyncMQTT_Generic v1.7.0 for Teensy 4.1 QNEthernet
Initialize Ethernet using DHCP => Connected! IP address:192.168.2.107
Connecting to MQTT...
Connected to MQTT broker: broker.emqx.io, port: 1883
PubTopic: async-mqtt/Teensy41_QNEthernet_Pub
************************************************
Session present: 0
Subscribing at QoS 2, packetId: 1
Publishing at QoS 0
Publishing at QoS 1, packetId: 2
Publishing at QoS 2, packetId: 3
************************************************
Subscribe acknowledged.
  packetId: 1
  qos: 2
Publish received.
  topic: async-mqtt/Teensy41_QNEthernet_Pub
  message: Teensy41_QNEthernet_Pub Test3
  qos: 2
  dup: 0
  retain: 1
  len: 29
  index: 0
  total: 29
Publish acknowledged.
  packetId: 2
Publish received.
  topic: async-mqtt/Teensy41_QNEthernet_Pub
  message: Teensy41_QNEthernet_Pub Test1
  qos: 0
  dup: 0
  retain: 0
  len: 29
  index: 0
  total: 29
Publish received.
  topic: async-mqtt/Teensy41_QNEthernet_Pub
  message: Teensy41_QNEthernet_Pub Test2
  qos: 1
  dup: 0
  retain: 0
  len: 29
  index: 0
  total: 29
Publish received.
  topic: async-mqtt/Teensy41_QNEthernet_Pub
  message: Teensy41_QNEthernet_Pub Test3
  qos: 2
  dup: 0
  retain: 0
  len: 29
  index: 0
  total: 29
Publish acknowledged.
  packetId: 3

2. FullyFeatured_QNEthernet on TEENSY 4.1 using StaticIP

Following is the debug terminal when running example FullyFeatured_QNEthernet on Teensy 4.1 using QNEthernet Library to demonstrate the operation of Async MQTT request, relied on Teensy41_AsyncTCP Library

Starting FullyFeatured_QNEthernet on TEENSY 4.1
AsyncMQTT_Generic v1.7.0 for Teensy 4.1 QNEthernet
Initialize Ethernet using static IP => Connected! IP address:192.168.2.222
Connecting to MQTT...
Connected to MQTT broker: broker.emqx.io, port: 1883
PubTopic: async-mqtt/Teensy41_QNEthernet_Pub
************************************************
Session present: 0
Subscribing at QoS 2, packetId: 1
Publishing at QoS 0
Publishing at QoS 1, packetId: 2
Publishing at QoS 2, packetId: 3
************************************************
Subscribe acknowledged.
  packetId: 1
  qos: 2
Publish received.
  topic: async-mqtt/Teensy41_QNEthernet_Pub
  message: Teensy41_QNEthernet_Pub Test3
  qos: 2
  dup: 0
  retain: 1
  len: 29
  index: 0
  total: 29
Publish acknowledged.
  packetId: 2
Publish received.
  topic: async-mqtt/Teensy41_QNEthernet_Pub
  message: Teensy41_QNEthernet_Pub Test1
  qos: 0
  dup: 0
  retain: 0
  len: 29
  index: 0
  total: 29
Publish received.
  topic: async-mqtt/Teensy41_QNEthernet_Pub
  message: Teensy41_QNEthernet_Pub Test2
  qos: 1
  dup: 0
  retain: 0
  len: 29
  index: 0
  total: 29
Publish received.
  topic: async-mqtt/Teensy41_QNEthernet_Pub
  message: Teensy41_QNEthernet_Pub Test3
  qos: 2
  dup: 0
  retain: 0
  len: 29
  index: 0
  total: 29
Publish acknowledged.
  packetId: 3


Debug

Debug is enabled by default on Serial.

You can also change the debugging level _TEENSY41_ASYNC_TCP_LOGLEVEL_ from 0 to 4 in the sketch.

#define _TEENSY41_ASYNC_TCP_LOGLEVEL_     1

Troubleshooting

If you get compilation errors, more often than not, you may need to install a newer version of the core for Arduino boards.

Sometimes, the library will only work if you update the board core to the latest version because I am using newly added functions.



Issues

Submit issues to: Teensy41_AsyncTCP issues


TO DO

  1. Search for bug and improvement.
  2. Teensy41_AsyncTCP_SSL library for Teensy 4.1 using QNEthernet Library
  3. Permit both TLS/SSL and non-TLS/SSL

DONE

  1. Add support to Teensy 4.1 using QNEthernet Library
  2. Add Table of Contents
  3. Add debug feature
  4. Use h-only style library
  5. Add example multiFileProject to demo for multiple-file project to avoid multiple-definitions linker error
  6. Fix issue with slow browsers or network
  7. Remove hard-code if possible
  8. Improve debug messages by adding functions to display error/state messages instead of cryptic error/state number
  9. Add astyle using allman style. Restyle the library


Contributions and Thanks

Many thanks for everyone for bug reporting, new feature suggesting, testing and contributing to the development of this library.

Contributions and Thanks

  1. Based on and modified from Hristo Gochkov's AsyncTCP. Many thanks to Hristo Gochkov for great ESPAsyncTCP Library and AsyncTCP Library
me-no-dev
⭐️⭐️ Hristo Gochkov


Contributing

If you want to contribute to this project:

  • Report bugs and errors
  • Ask for enhancements
  • Create issues and pull requests
  • Tell other people about this library


License

  • The library is licensed under LGPLv3

Copyright

  • Copyright (c) 2016- Hristo Gochkov
  • Copyright (c) 2022- Khoi Hoang

About

Asynchronous TCP Library for Teensy 4.1 using QNEthernet. This library is the base for future Async support for many current or future libraries, such as AsyncHTTPRequest_Generic, AsyncHTTPSRequest_Generic, AsyncMQTT_Generic, AsyncWebServer_Teensy41, AsyncUDP_Teensy41, AsyncDNSServer_Teensy41, AsyncTCP_SSL_Teensy41, etc.

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published