Initial version of nodemcuv2 dhcp serverHEADmain

Able to offer IP address + DNS/Gateway ...
Worked with devices at my hand.

1 files changed, 141 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5b1bb29
--- /dev/null
+++ b/README.md
@@ -0,0 +1,141 @@
+# pio-nodemcuv2-dhcp-server
+
+This repository implements a minimal [dhcp server][dhcp] on the [nodemcu v2]
+board using the [arduino] framework and the [PlatformIO][pio] build
+environment.
+
+
+## DHCP protocol
+
+All details of the dhcp protocol required for this implementation can be found
+in the following two RFCs
+- [rfc2131]: Dynamic Host Configuration Protocol
+- [rfc2132]: DHCP Options and BOOTP Vendor Extensions
+
+## Run
+
+Install PlatformIO core following the [installation guide][pio-install].
+
+```shell
+# Build the project.
+pio run
+
+# Run the test (only added host native tests).
+pio test
+
+# ... Attach nodemcu v2 board via USB.
+
+# Build and flash the embedded software.
+pio run -e nodemcuv2 -t upload
+
+# Connect to the serial monitor.
+pio device monitor -b 115200
+```
+
+> Check the [Makefile](Makefile) for reference.
+
+## Configuration
+
+The wifi client and dhcp server are currently configured with the following
+global variables in [main.cc](src/main.cc).
+
+```cpp
+/// -- WIFI access configuration.
+
+static constexpr char STATION_SSID[] = "<SSID>";
+static constexpr char STATION_WPA2[] = "<WPA2PW>";
+
+/// -- WIFI client config.
+
+static const IPAddress LOCAL_IP(10, 0, 0, 2);
+static const IPAddress GATEWAY(10, 0, 0, 1);
+static const IPAddress BROADCAST(10, 0, 0, 255);
+static const IPAddress SUBNET(255, 255, 255, 0);
+static const IPAddress DNS1(192, 168, 2, 1);
+
+/// -- DHCP lease config.
+
+static const IPAddress LEASE_START(10, 0, 0, 10);
+static constexpr u32 LEASE_TIME_SECS = 8 * 60 * 60; /* 8h */
+```
+
+## Why all this?
+
+My ultimate goal was to setup a **guest wifi** to isolate my home network while
+offering wifi to my guests.
+For that I planned to use of the baked in guest wifi feature of the router I
+got from my ISP.
+
+In my home network I am running [pi-hole] for blocking ads and trackers, which
+works by blocking those services on the DNS level. For this to function, all
+the devices in my home network need to use the pi-hole node as DNS server.
+This is typically done by letting the dhcp server distribute the DNS server to
+use (so it does not need to be configured on each device).
+Because the built-in dhcp server in the ISP router doesn't allow to configure
+the DNS server I disabled that one and run the optional dhcp server which comes
+with pi-hole.
+
+With that setup as starting point, one problem arises when using the guest wifi
+on the ISP router. Guest devices connected to the guest wifi don't see a dhcp
+server and hence don't get an IP address assigned. In turn, the setup is
+useless as I don't want guests to statically configure an IP address :^)
+
+Therefore the plan was to write a minimal dhcp server running on a [nodemcu v2]
+which would then linger in the guest wifi and distribute IP addresses to my
+guests.
+
+> Why a nodemcu v2? Because it has an wireless antenna and I had one laying
+> around collecting dust.
+
+So all in all my home setup would look something like the following.
+
+```
+   Home     +-----------+     Guest     +---------------+
+   Wifi (((-| ISP modem |-))) Wifi  (((-| nodemcuv2     |
+            |  & router |               | (dhcp server) |
+            +-----+-----+               +---------------+
+                  |
+          +-------+-------+
+          | pihole        |
+          | (dhcp server) |
+          +---------------+
+```
+
+## End of the story ...
+
+... I read the RFCs, developed & tested the dhcp server in my home network and
+then learned that the guests are isolated and I couldn't disable that isolation
+in the ISP router.
+
+At the end I couldn't deploy the guest wifi as planned but I had fun
+implementing the dhcp server and I guess learned something :^)
+
+For now I switched over to offering guest wifi by running an access point on
+the raspberry pi spanning a new sub-net and then doing NAT and iptables
+isolation to protect my home network. It's not ideal but it's sufficient for
+now.
+
+```
+   Home     +-----------+ 
+   Wifi (((-| ISP modem |
+            |  & router |
+            +-----+-----+
+                  |
+          +-------+-------+----------+    Guest
+          | pihole        | NAT      |-))) Wifi
+          | (dhcp server) | iptables |
+          +---------------+----------+
+```
+
+## License
+
+This project is licensed under the [MIT](LICENSE) license.
+
+[dhcp]: https://en.wikipedia.org/wiki/Dynamic_Host_Configuration_Protocol
+[rfc2131]: https://datatracker.ietf.org/doc/html/rfc2131
+[rfc2132]: https://datatracker.ietf.org/doc/html/rfc2132
+[pio]: https://platformio.org
+[pio-install]: https://docs.platformio.org/en/latest//core/installation.html
+[arduino]: https://docs.platformio.org/en/latest/frameworks/arduino.html
+[pi-hole]: https://pi-hole.net
+[nodemcu v2]: https://www.az-delivery.de/en/products/nodemcu