Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ofekp/tinyupnp
A very small UPnP IGD implementation for your ESP8266 for automatic port forwarding
https://github.com/ofekp/tinyupnp
esp32 esp8266 forwarding igd internet-of-things iot port port-forwarding router ssdp upnp
Last synced: 26 days ago
JSON representation
A very small UPnP IGD implementation for your ESP8266 for automatic port forwarding
- Host: GitHub
- URL: https://github.com/ofekp/tinyupnp
- Owner: ofekp
- License: lgpl-2.1
- Created: 2017-08-26T19:52:36.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2024-08-16T14:27:57.000Z (3 months ago)
- Last Synced: 2024-10-10T15:03:40.333Z (26 days ago)
- Topics: esp32, esp8266, forwarding, igd, internet-of-things, iot, port, port-forwarding, router, ssdp, upnp
- Language: C++
- Homepage:
- Size: 133 KB
- Stars: 103
- Watchers: 6
- Forks: 15
- Open Issues: 23
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# TinyUPnP
A very small UPnP IGD implementation for ESP8266 and ESP32.
# Installation
**TinyUPnP**
Simply clone or download as zip, then copy the folder TinyUPnP to your Arduino IDE "libraries" folder e.g "D:\Arduino\libraries".
If you are still unable to include the package, go to Arduino IDE preferences and make sure that sketchbook location points to the correct Arduino directory.
**Prerequisites**
Boards:
* ESP8266 - Follow https://randomnerdtutorials.com/how-to-install-esp8266-board-arduino-ide/
* ESP32 - Arduino IDE -> Board Manager -> search for "esp32" -> install esp32 by Espressif Systems (or by Arduino, according to your board version). For older Arduino IDE versions you can follow https://randomnerdtutorials.com/installing-the-esp32-board-in-arduino-ide-windows-instructions/
USB to UART Bridge Drivers:
* If you connect the ESP32 to your computer and it is not recognized in the Arduino IDE (i.e. it does not appear in Tools -> Port) you might need to install the drivers **CP210x USB to UART Bridge VCP** from https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers?tab=downloads
After extracting the ZIP file, updated the driver (on Win using the device manager), install it by picking the extracted directory manually.
Other Libraries:
* EasyDDNS (optional) - Used to tell your DDNS server what the IP of your Gateway Router is. To install:
Arduino IDE -> Sketch -> Include Library -> Manage Libraries -> search for "EasyDDNS" -> Install.
# Usage
**Please refer to the examples bundled with the TinyUPnP library.**
**Include**
```
#include "TinyUPnP.h"
#include // optional
```
**Declare**
```
TinyUPnP *tinyUPnP = new TinyUPnP(20000); // -1 for blocking (preferably, use a timeout value in [ms])
```
**Setup**
```
// you may repeat 'addPortMappingConfig' more than once
tinyUPnP->addPortMappingConfig(WiFi.localIP(), LISTEN_PORT, RULE_PROTOCOL_TCP, LEASE_DURATION, FRIENDLY_NAME);
// finally, commit the port mappings to the IGD
portMappingAdded = tinyUPnP->commitPortMappings();
```
**Loop**
```
// update UPnP port mapping every ms internal
// you can provide an optional method for reconnecting to the WiFi (otherwise leave as NULL)
tinyUPnP->updatePortMappings(600000, &connectWiFi); // 10 minutes
```
**API**
This is specific for the example code, you can do what you like here
```
http://:/?percentage=<0..100>
```
**Print**
```
// print all the port mappings that were configured using 'addPortMappingConfig' in the setup step
tinyUPnP->printPortMappingConfig();
// print all the current port mappings from the IGD
tinyUPnP->printAllPortMappings();
```
**Debug**
You can turn off debug prints by setting `UPNP_DEBUG` to `false` in [TinyUPnP.h#L16](https://github.com/ofekp/TinyUPnP/blob/master/src/TinyUPnP.h#L15)
# Issues
When reporting issues, attach full log (i.e `UPNP_DEBUG` is set to `true`) and add the serial output to the issue as a text file attachment.
# Donation
[](https://www.paypal.me/ofekpearl/1usd) If you like what I got, you can consider donating here, you can change the amount as you like.
:star: If not, starring this project will go a long way to help me too!
# For anyone interested in how the library works
1. It sends an M_SEARCH message to UPnP UDP multicast address.
2. The gateway router will respond with a message including an HTTP header called Location.
3. `Location` is a link to an XML file containing the IGD (Internet Gateway Device) API in order to create the needed calls which will add the new port mapping to your gateway router.
4. One of the services that is depicted in the XML is `urn:schemas-upnp-org:service:WANPPPConnection:1` which is what the library is looking for.
5. That service will include a `eventSubURL` tag which is a link to your router's IGD API. (The base URL is also depicted in the same file under the tag URLBase)
6. Using the base URL and the WANPPPConnection link you can issue an HTTP query to the router that will add the UPnP rule.
7. As a side note, the service depicted in the XML also includes a SCPDURL tag which is a link to another XML that depicts commands available for the service and their parameters. The package skips this stage as I assumed the query will be similar for many routers, this may very well not be the case, though, so it is up to you to check.
8. From this stage the package will issue the service command using an HTTP query to the router. The actual query can be seen in the code quite clearly but for anyone interested:
Headers:
```
"POST " + + " HTTP/1.1"
"Content-Type: text/xml; charset=\"utf-8\""
"SOAPAction: \"urn:schemas-upnp-org:service:WANPPPConnection:1#AddPortMapping\""
"Content-Length: " + body.length()
Body:
"\r\n"
"\r\n"
"\r\n"
"\r\n"
" \r\n"
" " + String(rulePort) + "\r\n"
" " + ruleProtocol + "\r\n"
" " + String(rulePort) + "\r\n"
" " + ipAddressToString(ruleIP) + "\r\n"
" 1\r\n"
" " + ruleFriendlyName + "\r\n"
" " + String(ruleLeaseDuration) + "\r\n"
"\r\n"
"\r\n"
"\r\n";
I hope this helps.
```
Referenced from my answer here:
https://stackoverflow.com/a/46267791/4295037
# Detailed Document Released by UPnP Forum
http://upnp.org/specs/arch/UPnP-arch-DeviceArchitecture-v2.0.pdf
# DDNS
You will also need a DDNS update service
I use this https://github.com/ayushsharma82/EasyDDNS
You can also see its usage in my example code [PWM_LEDServer.ino](https://github.com/ofekp/TinyUPnP/blob/master/examples/PWM_LEDServer/PWM_LEDServer.ino)
# Special thanks
[@ajwtech](https://github.com/ajwtech) - for contributing to the package by noting the need to use `constrolURL` instead of `eventSubURL`
[@Lan-Hekary](https://github.com/Lan-Hekary) - for improving the API
[@GIPdA](https://github.com/GIPdA) - for adding ESP32 support