Ethernet_Generic Library

[khoih-prog]

Ethernet_Generic library
How To Install Using Arduino Library Manager

---

Features

This Ethernet_Generic library is a port and modification to merge, as many as possible, the features of the following libraries
- Ethernet
- EthernetLarge
- Ethernet2
- Ethernet3

for AVR, Portenta_H7, Teensy, SAM DUE, Arduino SAMD21, Adafruit SAMD21/SAMD51, Adafruit nRF52, ESP32/ESP8266, STM32, RP2040-based, etc. boards using Ethernet W5x00 shields.

The h-only library now supports SPI2, most of EthernetLarge, Ethernet2 and Ethernet3 features by simply changing definitions in the sketch.

---

Currently supported Boards

This Ethernet_Generic library currently supports these following boards:

1. nRF52 boards, such as AdaFruit Feather nRF52832, nRF52840 Express, BlueFruit Sense, Itsy-Bitsy nRF52840 Express, Metro nRF52840 Express, NINA_B302_ublox, NINA_B112_ublox, etc.
2. SAM DUE
3. SAMD21

• Arduino SAMD21: ZERO, MKRs, NANO_33_IOT, etc.
• Adafruit SAMD21 (M0): ItsyBitsy M0, Feather M0, Feather M0 Express, Metro M0 Express, Circuit Playground Express, Trinket M0, PIRkey, Hallowing M0, Crickit M0, etc.
• Seeeduino: LoRaWAN, Zero, Femto M0, XIAO M0, Wio GPS Board, etc.

4. SAMD51

• Adafruit SAMD51 (M4): Metro M4, Grand Central M4, ItsyBitsy M4, Feather M4 Express, Trellis M4, Metro M4 AirLift Lite, MONSTER M4SK Express, Hallowing M4, etc.
• Seeeduino: Wio Terminal, Grove UI Wireless

5. Teensy (4.1, 4.0, 3.6, 3.5, 3,2, 3.1, 3.0, LC)

6. AVR Mega1280, 2560, ADK.

7. ESP32, using SPI or SPI2

8. ESP8266

9. RP2040-based boards, such as RASPBERRY_PI_PICO, ADAFRUIT_FEATHER_RP2040 and GENERIC_RP2040, using Arduino-mbed RP2040 core or Earle Philhower's arduino-pico core.

10. Portenta_H7

11. Arduino UNO WiFi Rev2, AVR_NANO_EVERY, etc.

Currently supported Ethernet shields/modules

1. W5x00 shield /module

---

---

Changelog

Releases v2.0.0

1. Initial porting and coding to merge, as many as possible, the features of the following libraries :

   • Ethernet
   • EthernetLarge
   • Ethernet2
   • Ethernet3

2. Add support to ESP32 SPI2

3. Convert to h-only library

4. Add debug feature

5. Optimize code to reduce compiled binary size

6. Add Packages' Patches

---

Examples

1. multiFileProject
2. TelnetClient
3. UdpNTPClient
4. UdpSendReceive
5. WebClient
6. WebClient_ESP
7. WebClient_ESP_SPI2
8. WebClientRepeating
9. WebClientRepeating_ESP
10. WebClientRepeating_ESP_SPI2
11. WebServer

---

Debug Terminal Output Samples

1. WebClientRepeating_ESP_SPI2 on ESP32_DEV

The following are debug terminal output when running example WebClientRepeating_ESP_SPI2 on ESP32_DEV with W5500 using Ethernet_Generic Library on SPI2

Starting WebClientRepeating_ESP_SPI2 on ESP32_DEV with W5x00 using Ethernet_Generic Library on SPI2
Ethernet_Generic v2.0.0
=========================
Currently Used SPI pinout:
MOSI:13
MISO:12
SCK:14
SS:5
=========================
Using mac index = 19
Connected! IP address: 192.168.2.95
Speed: 100 MB, Duplex: FULL DUPLEX, Link status: LINK

Starting connection to server...

Connecting...
HTTP/1.1 200 OK
Server: nginx/1.4.2
Date: Fri, 01 Apr 2022 19:00:28 GMT
Content-Type: text/plain
Content-Length: 2318
Last-Modified: Thu, 24 Feb 2022 11:33:35 GMT
Connection: close
Vary: Accept-Encoding
ETag: "62176d0f-90e"
Accept-Ranges: bytes

Please use http://arduino.tips/asciilogo.txt via HTTP

           `:;;;,`                      .:;;:.           
        .;;;;;;;;;;;`                :;;;;;;;;;;:     TM 
      `;;;;;;;;;;;;;;;`            :;;;;;;;;;;;;;;;      
     :;;;;;;;;;;;;;;;;;;         `;;;;;;;;;;;;;;;;;;     
    ;;;;;;;;;;;;;;;;;;;;;       .;;;;;;;;;;;;;;;;;;;;    
   ;;;;;;;;:`   `;;;;;;;;;     ,;;;;;;;;.`   .;;;;;;;;   
  .;;;;;;,         :;;;;;;;   .;;;;;;;          ;;;;;;;  
  ;;;;;;             ;;;;;;;  ;;;;;;,            ;;;;;;. 
 ,;;;;;               ;;;;;;.;;;;;;`              ;;;;;; 
 ;;;;;.                ;;;;;;;;;;;`      ```       ;;;;;`
 ;;;;;                  ;;;;;;;;;,       ;;;       .;;;;;
`;;;;:                  `;;;;;;;;        ;;;        ;;;;;
,;;;;`    `,,,,,,,,      ;;;;;;;      .,,;;;,,,     ;;;;;
:;;;;`    .;;;;;;;;       ;;;;;,      :;;;;;;;;     ;;;;;
:;;;;`    .;;;;;;;;      `;;;;;;      :;;;;;;;;     ;;;;;
.;;;;.                   ;;;;;;;.        ;;;        ;;;;;
 ;;;;;                  ;;;;;;;;;        ;;;        ;;;;;
 ;;;;;                 .;;;;;;;;;;       ;;;       ;;;;;,
 ;;;;;;               `;;;;;;;;;;;;                ;;;;; 
 `;;;;;,             .;;;;;; ;;;;;;;              ;;;;;; 
  ;;;;;;:           :;;;;;;.  ;;;;;;;            ;;;;;;  
   ;;;;;;;`       .;;;;;;;,    ;;;;;;;;        ;;;;;;;:  
    ;;;;;;;;;:,:;;;;;;;;;:      ;;;;;;;;;;:,;;;;;;;;;;   
    `;;;;;;;;;;;;;;;;;;;.        ;;;;;;;;;;;;;;;;;;;;    
      ;;;;;;;;;;;;;;;;;           :;;;;;;;;;;;;;;;;:     
       ,;;;;;;;;;;;;;,              ;;;;;;;;;;;;;;       
         .;;;;;;;;;`                  ,;;;;;;;;:         
                                                         
                                                         
                                                         
                                                         
    ;;;   ;;;;;`  ;;;;:  .;;  ;; ,;;;;;, ;;. `;,  ;;;;   
    ;;;   ;;:;;;  ;;;;;; .;;  ;; ,;;;;;: ;;; `;, ;;;:;;  
   ,;:;   ;;  ;;  ;;  ;; .;;  ;;   ,;,   ;;;,`;, ;;  ;;  
   ;; ;:  ;;  ;;  ;;  ;; .;;  ;;   ,;,   ;;;;`;, ;;  ;;. 
   ;: ;;  ;;;;;:  ;;  ;; .;;  ;;   ,;,   ;;`;;;, ;;  ;;` 
  ,;;;;;  ;;`;;   ;;  ;; .;;  ;;   ,;,   ;; ;;;, ;;  ;;  
  ;;  ,;, ;; .;;  ;;;;;:  ;;;;;: ,;;;;;: ;;  ;;, ;;;;;;  
  ;;   ;; ;;  ;;` ;;;;.   `;;;:  ,;;;;;, ;;  ;;,  ;;;;   

---

2. WebClient on MBED RASPBERRY_PI_PICO with Large Buffer

The following are debug terminal output when running example WebClient on MBED RASPBERRY_PI_PICO with W5500 using Ethernet_Generic Library and ArduinoCore-mbed mbed_rp2040 core

Starting WebClient on MBED RASPBERRY_PI_PICO with W5x00 using Ethernet_Generic Library with Large Buffer
=========================
Currently Used SPI pinout:
MOSI:19
MISO:16
SCK:18
SS:17
=========================
Using mac index = 16
Connected! IP address: 192.168.2.80
Speed: 100 MB, Duplex: FULL DUPLEX, Link status: LINK

Starting connection to server...
Connected to server
HTTP/1.1 200 OK
Server: nginx/1.4.2
Date: Sun, 03 Apr 2022 02:19:29 GMT
Content-Type: text/plain
Content-Length: 2317
Last-Modified: Thu, 24 Feb 2022 11:33:32 GMT
Connection: close
Vary: Accept-Encoding
ETag: "62176d0c-90d"
Accept-Ranges: bytes

Please use http://arduino.tips/asciilogo.txt via HTTP

           `:;;;,`                      .:;;:.           
        .;;;;;;;;;;;`                :;;;;;;;;;;:     TM 
      `;;;;;;;;;;;;;;;`            :;;;;;;;;;;;;;;;      
     :;;;;;;;;;;;;;;;;;;         `;;;;;;;;;;;;;;;;;;     
    ;;;;;;;;;;;;;;;;;;;;;       .;;;;;;;;;;;;;;;;;;;;    
   ;;;;;;;;:`   `;;;;;;;;;     ,;;;;;;;;.`   .;;;;;;;;   
  .;;;;;;,         :;;;;;;;   .;;;;;;;          ;;;;;;;  
  ;;;;;;             ;;;;;;;  ;;;;;;,            ;;;;;;. 
 ,;;;;;               ;;;;;;.;;;;;;`              ;;;;;; 
 ;;;;;.                ;;;;;;;;;;;`      ```       ;;;;;`
 ;;;;;                  ;;;;;;;;;,       ;;;       .;;;;;
`;;;;:                  `;;;;;;;;        ;;;        ;;;;;
,;;;;`    `,,,,,,,,      ;;;;;;;      .,,;;;,,,     ;;;;;
:;;;;`    .;;;;;;;;       ;;;;;,      :;;;;;;;;     ;;;;;
:;;;;`    .;;;;;;;;      `;;;;;;      :;;;;;;;;     ;;;;;
.;;;;.                   ;;;;;;;.        ;;;        ;;;;;
 ;;;;;                  ;;;;;;;;;        ;;;        ;;;;;
 ;;;;;                 .;;;;;;;;;;       ;;;       ;;;;;,
 ;;;;;;               `;;;;;;;;;;;;                ;;;;; 
 `;;;;;,             .;;;;;; ;;;;;;;              ;;;;;; 
  ;;;;;;:           :;;;;;;.  ;;;;;;;            ;;;;;;  
   ;;;;;;;`       .;;;;;;;,    ;;;;;;;;        ;;;;;;;:  
    ;;;;;;;;;:,:;;;;;;;;;:      ;;;;;;;;;;:,;;;;;;;;;;   
    `;;;;;;;;;;;;;;;;;;;.        ;;;;;;;;;;;;;;;;;;;;    
      ;;;;;;;;;;;;;;;;;           :;;;;;;;;;;;;;;;;:     
       ,;;;;;;;;;;;;;,              ;;;;;;;;;;;;;;       
         .;;;;;;;;;`                  ,;;;;;;;;:         
                                                         
                                                         
                                                         
                                                         
    ;;;   ;;;;;`  ;;;;:  .;;  ;; ,;;;;;, ;;. `;,  ;;;;   
    ;;;   ;;:;;;  ;;;;;; .;;  ;; ,;;;;;: ;;; `;, ;;;:;;  
   ,;:;   ;;  ;;  ;;  ;; .;;  ;;   ,;,   ;;;,`;, ;;  ;;  
   ;; ;:  ;;  ;;  ;;  ;; .;;  ;;   ,;,   ;;;;`;, ;;  ;;. 
   ;: ;;  ;;;;;:  ;;  ;; .;;  ;;   ,;,   ;;`;;;, ;;  ;;` 
  ,;;;;;  ;;`;;   ;;  ;; .;;  ;;   ,;,   ;; ;;;, ;;  ;;  
  ;;  ,;, ;; .;;  ;;;;;:  ;;;;;: ,;;;;;: ;;  ;;, ;;;;;;  
  ;;   ;; ;;  ;;` ;;;;.   `;;;:  ,;;;;;, ;;  ;;,  ;;;;   

Disconnecting from server...

[Juraj]

Hello Khoi. the Ethernet library repository has my new example PagerServer. If you could check if it works and include it in your new library. (I have a PR with the example in WiFiNINA too. it is included in esp8266 WiFi library too and of course it is in my WiFiEspAT too)

[khoih-prog]

Thanks @Juraj

Just modified, tested OK and add your example to the library as PagerServer

Starting PagerServer on MBED RASPBERRY_PI_PICO with W5x00 using Ethernet_Generic Library with Large Buffer
Ethernet_Generic v2.0.0
=========================
Currently Used SPI pinout:
MOSI:19
MISO:16
SCK:18
SS:17
=========================
Using mac index = 16
Connected! IP address: 192.168.2.80
Speed: 100 MB, Duplex: FULL DUPLEX, Link status: LINK

To access the server, connect with Telnet client to 192.168.2.80 2323
test
test ok

[khoih-prog]

Releases v2.0.1

1. Add support to SPI1 for RP2040 using Earle Philhower's arduino-pico core
2. Add example WebClientRepeating_RP2040_SPI1 to demo the new feature
3. Update Packages' Patches

Release v2.0.1 to add SPI1 support to RP2040 using arduino-pico core ·...

[khoih-prog]

Releases v2.1.0

1. Add support to WIZNet W5100S shield /module, such as WIZnet Ethernet HAT and W5100S-EVB-Pico. Check Wiznet W5100S #56 and Wiznet 5100 vs 5100s?

[khoih-prog]

Releases v2.2.0

1. Add support to STM32 boards using Arduino_Core_STM32
2. Add support to any board with core supporting custom hardware / software SPI, for example STM32.

---

Debug Terminal Output

1. WebClientRepeating on NUCLEO_F767ZI with W5x00 using Ethernet_Generic Library with SPI2

The following are debug terminal output when running example WebClientRepeating on NUCLEO_F767ZI with W5500 using Ethernet_Generic Library and SPI2

Start WebClientRepeating on NUCLEO_F767ZI with W5x00 using Ethernet_Generic Library with Large Buffer
Ethernet_Generic v2.2.0
[ETG] Default SPI pinout:
[ETG] MOSI: 22
[ETG] MISO: 25
[ETG] SCK: 23
[ETG] SS: 24
[ETG] =========================
[ETG] Board : NUCLEO_F767ZI , setCsPin: 24
[ETG] W5100 init, using SS_PIN_DEFAULT = 10 , new ss_pin =  10 , W5100Class::ss_pin =  24
[ETG] Chip is W5500
[ETG] W5100::init: W5500, SSIZE = 8192
[ETG] Currently Used SPI pinout:
[ETG] MOSI: 22
[ETG] MISO: 25
[ETG] SCK: 23
[ETG] SS: 24
[ETG] =========================
Connected! IP address: 192.168.2.123
Connecting...
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 02:21:30 GMT
Content-Type: text/plain
Content-Length: 2263
Connection: close
x-amz-id-2: 3UTJOk8AtRD5jCq+6bBOdAUucpho+KMM4ra+5/evX48oAT9NyZiaJbPNw5DOAr+amoxXbxbowX0=
x-amz-request-id: RB5W2BTZZ19E49PA
Last-Modified: Wed, 23 Feb 2022 14:56:42 GMT
ETag: "667cf48afcc12c38c8c1637947a04224"
CF-Cache-Status: DYNAMIC
Report-To: {"endpoints":[{"url":"https:\/\/a.nel.cloudflare.com\/report\/v3?s=GhwgztuLVJJhJBZt6cqr%2BYWDLWUzEcRPjVVpSU3Sz9KSRzj4q4DK9bvi1B2BSl7uxytKSSxOFBnKeekqPJw9LvpyYpYvHuOVcxatw924HWhtyK1OCApzLxZRLmobotQ%3D"}],"group":"cf-nel","max_age":604800}
NEL: {"success_fraction":0,"report_to":"cf-nel","max_age":604800}
Server: cloudflare
CF-RAY: 705586061d4354d9-YYZ
alt-svc: h3=":443"; ma=86400, h3-29=":443"; ma=86400


           `:;;;,`                      .:;;:.           
        .;;;;;;;;;;;`                :;;;;;;;;;;:     TM 
      `;;;;;;;;;;;;;;;`            :;;;;;;;;;;;;;;;      
     :;;;;;;;;;;;;;;;;;;         `;;;;;;;;;;;;;;;;;;     
    ;;;;;;;;;;;;;;;;;;;;;       .;;;;;;;;;;;;;;;;;;;;    
   ;;;;;;;;:`   `;;;;;;;;;     ,;;;;;;;;.`   .;;;;;;;;   
  .;;;;;;,         :;;;;;;;   .;;;;;;;          ;;;;;;;  
  ;;;;;;             ;;;;;;;  ;;;;;;,            ;;;;;;. 
 ,;;;;;               ;;;;;;.;;;;;;`              ;;;;;; 
 ;;;;;.                ;;;;;;;;;;;`      ```       ;;;;;`
 ;;;;;                  ;;;;;;;;;,       ;;;       .;;;;;
`;;;;:                  `;;;;;;;;        ;;;        ;;;;;
,;;;;`    `,,,,,,,,      ;;;;;;;      .,,;;;,,,     ;;;;;
:;;;;`    .;;;;;;;;       ;;;;;,      :;;;;;;;;     ;;;;;
:;;;;`    .;;;;;;;;      `;;;;;;      :;;;;;;;;     ;;;;;
.;;;;.                   ;;;;;;;.        ;;;        ;;;;;
 ;;;;;                  ;;;;;;;;;        ;;;        ;;;;;
 ;;;;;                 .;;;;;;;;;;       ;;;       ;;;;;,
 ;;;;;;               `;;;;;;;;;;;;                ;;;;; 
 `;;;;;,             .;;;;;; ;;;;;;;              ;;;;;; 
  ;;;;;;:           :;;;;;;.  ;;;;;;;            ;;;;;;  
   ;;;;;;;`       .;;;;;;;,    ;;;;;;;;        ;;;;;;;:  
    ;;;;;;;;;:,:;;;;;;;;;:      ;;;;;;;;;;:,;;;;;;;;;;   
    `;;;;;;;;;;;;;;;;;;;.        ;;;;;;;;;;;;;;;;;;;;    
      ;;;;;;;;;;;;;;;;;           :;;;;;;;;;;;;;;;;:     
       ,;;;;;;;;;;;;;,              ;;;;;;;;;;;;;;       
         .;;;;;;;;;`                  ,;;;;;;;;:         
                                                         
                                                         
                                                         
                                                         
    ;;;   ;;;;;`  ;;;;:  .;;  ;; ,;;;;;, ;;. `;,  ;;;;   
    ;;;   ;;:;;;  ;;;;;; .;;  ;; ,;;;;;: ;;; `;, ;;;:;;  
   ,;:;   ;;  ;;  ;;  ;; .;;  ;;   ,;,   ;;;,`;, ;;  ;;  
   ;; ;:  ;;  ;;  ;;  ;; .;;  ;;   ,;,   ;;;;`;, ;;  ;;. 
   ;: ;;  ;;;;;:  ;;  ;; .;;  ;;   ,;,   ;;`;;;, ;;  ;;` 
  ,;;;;;  ;;`;;   ;;  ;; .;;  ;;   ,;,   ;; ;;;, ;;  ;;  
  ;;  ,;, ;; .;;  ;;;;;:  ;;;;;: ,;;;;;: ;;  ;;, ;;;;;;  
  ;;   ;; ;;  ;;` ;;;;.   `;;;:  ,;;;;;, ;;  ;;,  ;;;;   

[khoih-prog]

Releases v2.3.0

1. Add support to custom SPI for RP2040, Nano_RP2040_Connect, Portenta_H7, etc. using Arduino-mbed core

---

Debug Terminal Output

1. WebClientRepeating_RP2040_SPI1 on MBED RASPBERRY_PI_PICO with W5x00 using Ethernet_Generic Library with Large Buffer

The following are debug terminal output when running example WebClientRepeating_RP2040_SPI1 on MBED RASPBERRY_PI_PICO with W5500 using Ethernet_Generic Library and SPI2

Starting WebClientRepeating_RP2040_SPI1 on MBED RASPBERRY_PI_PICO with W5x00 using Ethernet_Generic Library with Large Buffer
Ethernet_Generic v2.3.0
[ETG] Default SPI pinout:
[ETG] MOSI: 15
[ETG] MISO: 12
[ETG] SCK: 14
[ETG] SS: 13
[ETG] =========================
[ETG] RPIPICO setCsPin: 13
[ETG] W5100 init, using SS_PIN_DEFAULT = 13 , new ss_pin =  10 , W5100Class::ss_pin =  13
[ETG] Chip is W5500
[ETG] W5100::init: W5500, SSIZE = 8192
[ETG] Currently Used SPI pinout:
[ETG] MOSI: 15
[ETG] MISO: 12
[ETG] SCK: 14
[ETG] SS: 13
[ETG] =========================
Using mac index = 18
Connected! IP address: 192.168.2.85
Speed: 100 MB, Duplex: FULL DUPLEX, Link status: LINK

Connecting...
HTTP/1.1 200 OK
Date: Wed, 04 May 2022 02:52:56 GMT
Content-Type: text/plain
Content-Length: 2263
Connection: close
x-amz-id-2: 8vpqIozCfHQtWmljz3zKcVb5oa2m61jwYMh4PaSUwllVqFPdlotFeMd8kbtXto0B1tOusMAUwRI=
x-amz-request-id: 625R5E0MEMACW8E3
Last-Modified: Wed, 23 Feb 2022 14:56:42 GMT
ETag: "667cf48afcc12c38c8c1637947a04224"
CF-Cache-Status: DYNAMIC
Report-To: {"endpoints":[{"url":"https:\/\/a.nel.cloudflare.com\/report\/v3?s=PtWJxKSeTy2pn3lC8%2FpwyFTn96Mj1T%2B%2FKoMsFHN4IUM4loCow6T01wiMe%2BJzJMIHZS2np%2F8CCNhjwRu%2FwSpDwtwl%2FoD7YPSnSCxjiAChJ7n%2FZq2yn1s5yBTBQf6op8M%3D"}],"group":"cf-nel","max_age":604800}
NEL: {"success_fraction":0,"report_to":"cf-nel","max_age":604800}
Server: cloudflare
CF-RAY: 705df1758fde3fde-YYZ
alt-svc: h3=":443"; ma=86400, h3-29=":443"; ma=86400


           `:;;;,`                      .:;;:.           
        .;;;;;;;;;;;`                :;;;;;;;;;;:     TM 
      `;;;;;;;;;;;;;;;`            :;;;;;;;;;;;;;;;      
     :;;;;;;;;;;;;;;;;;;         `;;;;;;;;;;;;;;;;;;     
    ;;;;;;;;;;;;;;;;;;;;;       .;;;;;;;;;;;;;;;;;;;;    
   ;;;;;;;;:`   `;;;;;;;;;     ,;;;;;;;;.`   .;;;;;;;;   
  .;;;;;;,         :;;;;;;;   .;;;;;;;          ;;;;;;;  
  ;;;;;;             ;;;;;;;  ;;;;;;,            ;;;;;;. 
 ,;;;;;               ;;;;;;.;;;;;;`              ;;;;;; 
 ;;;;;.                ;;;;;;;;;;;`      ```       ;;;;;`
 ;;;;;                  ;;;;;;;;;,       ;;;       .;;;;;
`;;;;:                  `;;;;;;;;        ;;;        ;;;;;
,;;;;`    `,,,,,,,,      ;;;;;;;      .,,;;;,,,     ;;;;;
:;;;;`    .;;;;;;;;       ;;;;;,      :;;;;;;;;     ;;;;;
:;;;;`    .;;;;;;;;      `;;;;;;      :;;;;;;;;     ;;;;;
.;;;;.                   ;;;;;;;.        ;;;        ;;;;;
 ;;;;;                  ;;;;;;;;;        ;;;        ;;;;;
 ;;;;;                 .;;;;;;;;;;       ;;;       ;;;;;,
 ;;;;;;               `;;;;;;;;;;;;                ;;;;; 
 `;;;;;,             .;;;;;; ;;;;;;;              ;;;;;; 
  ;;;;;;:           :;;;;;;.  ;;;;;;;            ;;;;;;  
   ;;;;;;;`       .;;;;;;;,    ;;;;;;;;        ;;;;;;;:  
    ;;;;;;;;;:,:;;;;;;;;;:      ;;;;;;;;;;:,;;;;;;;;;;   
    `;;;;;;;;;;;;;;;;;;;.        ;;;;;;;;;;;;;;;;;;;;    
      ;;;;;;;;;;;;;;;;;           :;;;;;;;;;;;;;;;;:     
       ,;;;;;;;;;;;;;,              ;;;;;;;;;;;;;;       
         .;;;;;;;;;`                  ,;;;;;;;;:         
                                                         
                                                         
                                                         
                                                         
    ;;;   ;;;;;`  ;;;;:  .;;  ;; ,;;;;;, ;;. `;,  ;;;;   
    ;;;   ;;:;;;  ;;;;;; .;;  ;; ,;;;;;: ;;; `;, ;;;:;;  
   ,;:;   ;;  ;;  ;;  ;; .;;  ;;   ,;,   ;;;,`;, ;;  ;;  
   ;; ;:  ;;  ;;  ;;  ;; .;;  ;;   ,;,   ;;;;`;, ;;  ;;. 
   ;: ;;  ;;;;;:  ;;  ;; .;;  ;;   ,;,   ;;`;;;, ;;  ;;` 
  ,;;;;;  ;;`;;   ;;  ;; .;;  ;;   ,;,   ;; ;;;, ;;  ;;  
  ;;  ,;, ;; .;;  ;;;;;:  ;;;;;: ,;;;;;: ;;  ;;, ;;;;;;  
  ;;   ;; ;;  ;;` ;;;;.   `;;;:  ,;;;;;, ;;  ;;,  ;;;;