Skip to content
Very simple DNS async server for micropython
Python
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
test
tinydns
.gitignore
.travis.yml
LICENSE
README.md

README.md

TinyDNS Build Status

Simple and lightweight (thus - tiny) DNS server for tiny devices like ESP8266 / ESP32 running micropython. Sometimes people needs very simple DNS just to server a few domains. For example - very common use case is captive portal

Features

  • Fully asynchronous using uasyncio library for MicroPython.
  • Tiny memory usage. So you can run it on devices like ESP8266 / ESP32 with 64K/96K of RAM onboard.
  • Great unittest coverage. So you can be confident about quality :)

Requirements

Quickstart

TinyDNS comes as a compiled firmware for ESP8266 / ESP32 as well ("frozen modules"). You don't have to use it - however, it could be easiest way to try it :) Instructions below are tested with NodeMCU devices. For your device instructions could be slightly different, so keep in mind. CAUTION: If you proceed with installation all data on your device will lost!

Installation - ESP8266

  • Download latest firmware_esp8266.bin from releases.
  • Install esp-tool if you haven't done already: pip install esptool
  • Erase flash: esptool.py --port <UART PORT> --baud 115200 erase_flash
  • Flash firmware: esptool.py --port <UART PORT> --baud 115200 write_flash -fm dio 0 firmware_esp8266.bin

Installation - ESP32

  • Download latest firmware_esp32.bin from releases.
  • Install esp-tool if you haven't done already: pip install esptool
  • Erase flash: esptool.py --port <UART PORT> --baud 115200 erase_flash
  • Flash firmware: esptool.py --port <UART PORT> --baud 115200 write_flash -fm dio 0x1000 firmware_esp32.bin

Let's code

Coming very soon!

Limitation / Known issues

  • UDP only
  • IPv4 only (therefore only A queries)
  • Simple DNS requests only: 1 DNS query per packet (99% of DNS requests)

Reference

class Server

  • __init__(self, domains={}, ttl=10, max_pkt_len=512, ignore_unknown=False) - create tinydns server instance.

    • domains - dict of domains to resolve - domain -> IPv4. E.g. {'my.com': '192.168.1.1', 'yep.com': '127.0.0.1'}
    • ttl - Response TimeToLive, i.e. how long answer can be stored in the cache.
    • max_pkt_len - Maximum UDP packet length to serve. Due to memory constrained devices it is good to restrict datagram size.
    • ignore_unknown - Controls behavior for unknown domain case. If turned on - no error response will be generated.
  • add_domain(self, domain, ip) - add domain to resolved to ip. All parameters are str.

  • run(self, host='127.0.0.1', port=53) - run DNS server. Because of tinydns is fully async server and assumption here is you're running it as a part of some main application so it will not call loop_forever().

    • host - host to listen on
    • port - port to listen on

More documentation and examples coming soon! :)

You can’t perform that action at this time.