|
| 1 | +# AsyncDNSServer_RP2040W |
| 2 | + |
| 3 | + |
| 4 | +[](https://www.ardu-badge.com/AsyncDNSServer_RP2040W) |
| 5 | +[](https://github.com/khoih-prog/AsyncDNSServer_RP2040W/releases) |
| 6 | +[](#Contributing) |
| 7 | +[](http://github.com/khoih-prog/AsyncDNSServer_RP2040W/issues) |
| 8 | + |
| 9 | +<a href="https://www.buymeacoffee.com/khoihprog6" title="Donate to my libraries using BuyMeACoffee"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Donate to my libraries using BuyMeACoffee" style="height: 50px !important;width: 181px !important;" ></a> |
| 10 | +<a href="https://www.buymeacoffee.com/khoihprog6" title="Donate to my libraries using BuyMeACoffee"><img src="https://img.shields.io/badge/buy%20me%20a%20coffee-donate-orange.svg?logo=buy-me-a-coffee&logoColor=FFDD00" style="height: 20px !important;width: 200px !important;" ></a> |
| 11 | + |
| 12 | +--- |
| 13 | +--- |
| 14 | + |
| 15 | +## Table of Contents |
| 16 | + |
| 17 | + |
| 18 | +* [Why do we need this AsyncDNSServer_RP2040W library](#why-do-we-need-this-AsyncDNSServer_RP2040W-library) |
| 19 | + * [Features](#features) |
| 20 | + * [Why Async is better](#why-async-is-better) |
| 21 | + * [Currently Supported Boards](#currently-supported-boards) |
| 22 | +* [Changelog](changelog.md) |
| 23 | +* [Prerequisites](#prerequisites) |
| 24 | +* [Installation](#installation) |
| 25 | + * [Use Arduino Library Manager](#use-arduino-library-manager) |
| 26 | + * [Manual Install](#manual-install) |
| 27 | + * [VS Code & PlatformIO](#vs-code--platformio) |
| 28 | +* [HOWTO Fix `Multiple Definitions` Linker Error](#howto-fix-multiple-definitions-linker-error) |
| 29 | +* [HOWTO Setting up the Async DNS Server](#howto-setting-up-the-async-dns-server) |
| 30 | +* [Examples](#examples) |
| 31 | + * [ 1. AsyncCaptivePortal](examples/AsyncCaptivePortal) |
| 32 | + * [ 2. AsyncCaptivePortalAdvanced](examples/AsyncCaptivePortalAdvanced) |
| 33 | + * [ 3. AsyncDNServerFull](examples/AsyncDNServerFull) |
| 34 | + * [ 4. AsyncDNSServer](examples/AsyncDNSServer) |
| 35 | + * [ 5. multiFileProject](examples/multiFileProject) |
| 36 | +* [Example AsyncDNSServer](#example-AsyncDNSServer) |
| 37 | + * [1. File AsyncDNSServer.ino](#1-file-AsyncDNSServerino) |
| 38 | + * [2. File defines.h](#2-file-definesh) |
| 39 | +* [Debug](#debug) |
| 40 | +* [Troubleshooting](#troubleshooting) |
| 41 | +* [Issues](#issues) |
| 42 | +* [TO DO](#to-do) |
| 43 | +* [DONE](#done) |
| 44 | +* [Contributions and Thanks](#contributions-and-thanks) |
| 45 | +* [Contributing](#contributing) |
| 46 | +* [License](#license) |
| 47 | +* [Copyright](#copyright) |
| 48 | + |
| 49 | +--- |
| 50 | +--- |
| 51 | + |
| 52 | +### Why do we need this [AsyncDNSServer_RP2040W library](https://github.com/khoih-prog/AsyncDNSServer_RP2040W) |
| 53 | + |
| 54 | +#### Features |
| 55 | + |
| 56 | +This [AsyncDNSServer_RP2040W library](https://github.com/khoih-prog/AsyncDNSServer_RP2040W) is a fully asynchronous DNSServer library, designed for a trouble-free, multi-connection network environment, for **RASPBERRY_PI_PICO_W using CYW43439 WiFi**. |
| 57 | + |
| 58 | +This library is based on, modified from: |
| 59 | + |
| 60 | +1. [Develo's ESPAsyncDNSServer](https://github.com/devyte/ESPAsyncDNSServer) |
| 61 | +2. [AsyncDNSServer_STM32](https://github.com/khoih-prog/AsyncDNSServer_STM32) |
| 62 | + |
| 63 | +to apply the better and faster **asynchronous** feature into **RASPBERRY_PI_PICO_W using CYW43439 WiFi**. |
| 64 | + |
| 65 | + |
| 66 | +#### Why Async is better |
| 67 | + |
| 68 | +- Using asynchronous network means that you can handle **more than one connection at the same time** |
| 69 | +- You are called once the packet is ready |
| 70 | +- After a DNS Client connected to this Async DNS server, you are **immediately ready** to handle other connections while the Server is taking care of receiving and responding to the UDP packets in the background. |
| 71 | +- You are not required to check in a tight loop() the arrival of the DNS requesting packets to process them. |
| 72 | +- **Speed is OMG** |
| 73 | + |
| 74 | +--- |
| 75 | + |
| 76 | +### Currently Supported Boards |
| 77 | + |
| 78 | +1. **RASPBERRY_PI_PICO_W with CYW43439 WiFi** using [**arduino-pico core v2.4.0+**](https://github.com/earlephilhower/arduino-pico) |
| 79 | + |
| 80 | +<p align="center"> |
| 81 | + <img src="https://github.com/khoih-prog/AsyncDNSServer_RP2040W/blob/main/pics/RP2040W-pinout.svg"> |
| 82 | +</p> |
| 83 | + |
| 84 | + |
| 85 | +--- |
| 86 | +--- |
| 87 | + |
| 88 | +## Prerequisites |
| 89 | + |
| 90 | + 1. [`Arduino IDE 1.8.19+` for Arduino](https://github.com/arduino/Arduino). [](https://github.com/arduino/Arduino/releases/latest) |
| 91 | + 2. [`Earle Philhower's arduino-pico core v2.4.0+`](https://github.com/earlephilhower/arduino-pico) for **RASPBERRY_PI_PICO_W with CYW43439 WiFi**, etc. [](https://github.com/earlephilhower/arduino-pico/releases/latest) |
| 92 | + 3. [`AsyncUDP_RP2040W library v1.0.0+`](https://github.com/khoih-prog/AsyncUDP_RP2040W) for RASPBERRY_PI_PICO_W with CYW43439 WiFi. To install. check [](https://www.ardu-badge.com/AsyncUDP_RP2040W) |
| 93 | + |
| 94 | +--- |
| 95 | + |
| 96 | +### Installation |
| 97 | + |
| 98 | +The suggested way to install is to: |
| 99 | + |
| 100 | +#### Use Arduino Library Manager |
| 101 | + |
| 102 | +The best way is to use `Arduino Library Manager`. Search for `AsyncDNSServer_RP2040W`, then select / install the latest version. You can also use this link [](https://www.ardu-badge.com/AsyncDNSServer_RP2040W) for more detailed instructions. |
| 103 | + |
| 104 | +### Manual Install |
| 105 | + |
| 106 | +1. Navigate to [AsyncDNSServer_RP2040W](https://github.com/khoih-prog/AsyncDNSServer_RP2040W) page. |
| 107 | +2. Download the latest release `AsyncDNSServer_RP2040W-main.zip`. |
| 108 | +3. Extract the zip file to `AsyncDNSServer_RP2040W-main` directory |
| 109 | +4. Copy the whole `AsyncDNSServer_RP2040W-main` folder to Arduino libraries' directory such as `~/Arduino/libraries/`. |
| 110 | + |
| 111 | +### VS Code & PlatformIO: |
| 112 | + |
| 113 | +1. Install [VS Code](https://code.visualstudio.com/) |
| 114 | +2. Install [PlatformIO](https://platformio.org/platformio-ide) |
| 115 | +3. Install [**AsyncDNSServer_RP2040W** library](https://registry.platformio.org/libraries/khoih-prog/AsyncDNSServer_RP2040W) by using [Library Manager](https://registry.platformio.org/libraries/khoih-prog/AsyncDNSServer_RP2040W/installation). Search for AsyncDNSServer_RP2040W in [Platform.io Author's Libraries](https://platformio.org/lib/search?query=author:%22Khoi%20Hoang%22) |
| 116 | +4. Use included [platformio.ini](platformio/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](https://docs.platformio.org/page/projectconf.html) |
| 117 | + |
| 118 | + |
| 119 | +--- |
| 120 | +--- |
| 121 | + |
| 122 | +### HOWTO Fix `Multiple Definitions` Linker Error |
| 123 | + |
| 124 | +The current library implementation, using `xyz-Impl.h` instead of standard `xyz.cpp`, possibly creates certain `Multiple Definitions` Linker error in certain use cases. |
| 125 | + |
| 126 | +You can include this `.hpp` file |
| 127 | + |
| 128 | +``` |
| 129 | +// Can be included as many times as necessary, without `Multiple Definitions` Linker Error |
| 130 | +#include "AsyncDNSServer_RP2040W.hpp" //https://github.com/khoih-prog/AsyncDNSServer_RP2040W |
| 131 | +``` |
| 132 | + |
| 133 | +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 |
| 134 | + |
| 135 | +``` |
| 136 | +// To be included only in main(), .ino with setup() to avoid `Multiple Definitions` Linker Error |
| 137 | +#include "AsyncDNSServer_RP2040W.h" //https://github.com/khoih-prog/AsyncDNSServer_RP2040W |
| 138 | +``` |
| 139 | + |
| 140 | +Check the new [**multiFileProject** example](examples/multiFileProject) for a `HOWTO` demo. |
| 141 | + |
| 142 | +Have a look at the discussion in [Different behaviour using the src_cpp or src_h lib #80](https://github.com/khoih-prog/ESPAsync_WiFiManager/discussions/80) |
| 143 | + |
| 144 | + |
| 145 | +--- |
| 146 | +--- |
| 147 | + |
| 148 | +## HOWTO Setting up the Async DNS Server |
| 149 | + |
| 150 | + |
| 151 | +```cpp |
| 152 | + |
| 153 | +#include <AsyncDNSServer_RP2040W.h> |
| 154 | + |
| 155 | +const byte DNS_PORT = 53; |
| 156 | + |
| 157 | +IPAddress apIP; |
| 158 | + |
| 159 | +AsyncDNSServer dnsServer; |
| 160 | + |
| 161 | + |
| 162 | +void setup() |
| 163 | +{ |
| 164 | + ... |
| 165 | + |
| 166 | + // modify TTL associated with the domain name (in seconds) |
| 167 | + // default is 60 seconds |
| 168 | + dnsServer.setTTL(300); |
| 169 | + // set which return code will be used for all other domains |
| 170 | + // (e.g. sending ServerFailure instead of NonExistentDomain will reduce number of queries |
| 171 | + // sent by clients). Default is AsyncDNSReplyCode::NonExistentDomain |
| 172 | + dnsServer.setErrorReplyCode(AsyncDNSReplyCode::ServerFailure); |
| 173 | + |
| 174 | + // start DNS server for a specific domain name |
| 175 | + dnsServer.start(DNS_PORT, "*", Ethernet.localIP()); |
| 176 | + |
| 177 | + ... |
| 178 | +} |
| 179 | + |
| 180 | +void loop() |
| 181 | +{ |
| 182 | +} |
| 183 | + |
| 184 | +``` |
| 185 | + |
| 186 | +--- |
| 187 | +--- |
| 188 | + |
| 189 | + |
| 190 | +### Examples |
| 191 | + |
| 192 | + |
| 193 | + 1. [AsyncCaptivePortal](examples/AsyncCaptivePortal) |
| 194 | + 2. [AsyncCaptivePortalAdvanced](examples/AsyncCaptivePortalAdvanced) |
| 195 | + 3. [AsyncDNServerFull](examples/AsyncDNServerFull) |
| 196 | + 4. [AsyncDNSServer](examples/AsyncDNSServer) |
| 197 | + 5. [multiFileProject](examples/multiFileProject) |
| 198 | + |
| 199 | +--- |
| 200 | + |
| 201 | +### Example [AsyncDNSServer](examples/AsyncDNSServer) |
| 202 | + |
| 203 | +#### 1. File [AsyncDNSServer.ino](examples/AsyncDNSServer/AsyncDNSServer.ino) |
| 204 | + |
| 205 | + |
| 206 | +https://github.com/khoih-prog/AsyncDNSServer_RP2040W/blob/c9325a8c6accb27c5df1c7d29a209d2d064cda10/examples/AsyncDNSServer/AsyncDNSServer.ino#L10-L119 |
| 207 | + |
| 208 | + |
| 209 | +#### 2. File [defines.h](examples/AsyncDNSServer/defines.h) |
| 210 | + |
| 211 | +https://github.com/khoih-prog/AsyncDNSServer_RP2040W/blob/c9325a8c6accb27c5df1c7d29a209d2d064cda10/examples/AsyncDNSServer/defines.h#L1-L29 |
| 212 | + |
| 213 | + |
| 214 | +--- |
| 215 | +--- |
| 216 | + |
| 217 | +### Debug |
| 218 | + |
| 219 | +Debug is enabled by default on Serial. To disable, use level 0 |
| 220 | + |
| 221 | +```cpp |
| 222 | +#define ASYNC_DNS_RP2040W_DEBUG_PORT Serial |
| 223 | + |
| 224 | +// Use from 0 to 4. Higher number, more debugging messages and memory usage. |
| 225 | +#define _ASYNC_DNS_RP2040W_LOGLEVEL_ 0 |
| 226 | +``` |
| 227 | + |
| 228 | +You can also change the debugging level from 0 to 4 |
| 229 | + |
| 230 | +```cpp |
| 231 | +#define ASYNC_DNS_RP2040W_DEBUG_PORT Serial |
| 232 | + |
| 233 | + |
| 234 | +// Use from 0 to 4. Higher number, more debugging messages and memory usage. |
| 235 | +#define _ASYNC_DNS_RP2040W_LOGLEVEL_ 4 |
| 236 | +``` |
| 237 | + |
| 238 | +--- |
| 239 | + |
| 240 | +### Troubleshooting |
| 241 | + |
| 242 | +If you get compilation errors, more often than not, you may need to install a newer version of the [**arduino-pico core**](https://github.com/earlephilhower/arduino-pico) |
| 243 | + |
| 244 | +Sometimes, the library will only work if you update the [**arduino-pico core**](https://github.com/earlephilhower/arduino-pico) core to the latest version because I am using newly added functions. |
| 245 | + |
| 246 | + |
| 247 | +--- |
| 248 | +--- |
| 249 | + |
| 250 | + |
| 251 | +### Issues |
| 252 | + |
| 253 | +Submit issues to: [AsyncDNSServer_RP2040W issues](https://github.com/khoih-prog/AsyncDNSServer_RP2040W/issues) |
| 254 | + |
| 255 | +--- |
| 256 | + |
| 257 | +## TO DO |
| 258 | + |
| 259 | + 1. Fix bug. Add enhancement |
| 260 | + |
| 261 | + |
| 262 | +## DONE |
| 263 | + |
| 264 | + 1. Add support to RASPBERRY_PI_PICO_W using CYW43439 WiFi |
| 265 | + 2. Add more examples. |
| 266 | + 3. Add debugging features. |
| 267 | + |
| 268 | +--- |
| 269 | +--- |
| 270 | + |
| 271 | +### Contributions and Thanks |
| 272 | + |
| 273 | +1. Based on and modified from [Develo's ESPAsyncDNSServer Library](https://github.com/devyte/ESPAsyncDNSServer). |
| 274 | + |
| 275 | + |
| 276 | +<table> |
| 277 | + <tr> |
| 278 | + <td align="center"><a href="https://github.com/devyte"><img src="https://github.com/devyte.png" width="100px;" alt="devyte"/><br/><sub><b>⭐️ Develo</b></sub></a><br/></td> |
| 279 | + </tr> |
| 280 | +</table> |
| 281 | + |
| 282 | +--- |
| 283 | + |
| 284 | +### Contributing |
| 285 | + |
| 286 | +If you want to contribute to this project: |
| 287 | +- Report bugs and errors |
| 288 | +- Ask for enhancements |
| 289 | +- Create issues and pull requests |
| 290 | +- Tell other people about this library |
| 291 | + |
| 292 | +--- |
| 293 | + |
| 294 | +### License |
| 295 | + |
| 296 | +- The library is licensed under [GPLv3](https://github.com/khoih-prog/AsyncDNSServer_RP2040W/blob/main/LICENSE) |
| 297 | + |
| 298 | +--- |
| 299 | + |
| 300 | +## Copyright |
| 301 | + |
| 302 | +- Copyright 2016- Develo |
| 303 | +- Copyright 2022- Khoi Hoang |
| 304 | + |
0 commit comments