Skip to content

Very simple DNS async server for micropython

License

Notifications You must be signed in to change notification settings

belyalov/tinydns

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

8 Commits
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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! :)

About

Very simple DNS async server for micropython

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages