MicroWebSrv: A Python repository from jczic

Also check out the new ESP32 MPY-Jama free IDE and the latest MicroWebSrv2 below:

MicroWebSrv is a micro HTTP Web server that supports WebSockets, html/python language templating and routing handlers, for MicroPython (principally used on ESP32 and Pycom modules. Now supports all variants of Pyboard D-series from the makers of Micropython)

Very easy to integrate and very light with 3 files only :

"microWebSrv.py" - The Web server
"microWebSocket.py" - The optional support of WebSockets
"microWebTemplate.py" - The optional templating language for .pyhtml rendered pages

Mini tuto in video by rdagger68 :

https://www.youtube.com/watch?v=xscBwC1SrF4

Simple but effective :

Use it to embed a cool Web site in yours modules
Handle GET, POST, ... requests to interract with user and configure options
Exchange in JSON format on HTTP methods to make an embedded fullREST API
Serve files on the fly to export any data to the user
Use routes and variable route handlers
Play with AjAX to interact speedly with a Web application
Make it a captive portal simply
Use WebSockets for fast and powerful data exchange
Make html/python files for rendering more efficient web pages

Using microWebSrv main class :

Name	Function
Constructor	`mws = MicroWebSrv(routeHandlers=None, port=80, bindIP='0.0.0.0', webPath="/flash/www")`
Start Web server	`mws.Start(threaded=True)`
Stop Web server	`mws.Stop()`
Check if Web server is running	`mws.IsStarted()`
Set URL location for not found page	`mws.SetNotFoundPageUrl(url=None)`
Get mime type from file extention	`mws.GetMimeTypeFromFilename(filename)`
Get handler function from route	`(routeHandler, routeArgs) = mws.GetRouteHandler(resUrl, method)`
Callback function to enable and accept WebSockets	`mws.AcceptWebSocketCallback = _acptWS` `_acptWS(webSocket, httpClient) { }`
Maximum length of memory allocated to receive WebSockets data (1024 by default)	`mws.MaxWebSocketRecvLen`
New thread used for each WebSocket connection (True by default)	`mws.WebSocketThreaded`
Escape string to HTML usage	`MicroWebSrv.HTMLEscape(s)`

Basic example :

from microWebSrv import MicroWebSrv
mws = MicroWebSrv()      # TCP port 80 and files in /flash/www
mws.Start(threaded=True) # Starts server in a new thread

Using as captive portal :

# To intercept all not found queries and redirect it,
mws.SetNotFoundPageUrl("http://my-device.wifi")

Can be used with MicroDNSSrv easily.

Using route handlers example :

routeHandlers = [
  ( "relative_url_route_1", "METHOD", handlerFunc_1 ),
  ( "relative_url_route_2", "METHOD", handlerFunc_2 ),
  ( ... )
]

def handlerFunc_1(httpClient, httpResponse, routeArgs=None) :
  print("In HTTP handler 1")

def handlerFunc_2(httpClient, httpResponse, routeArgs=None) :
  print("In HTTP handler 2")

Using directly route handlers decorators example :

@MicroWebSrv.route('/get-test')
def handlerFuncGet(httpClient, httpResponse) :
  print("In GET-TEST HTTP")

@MicroWebSrv.route('/post-test', 'POST')
def handlerFuncPost(httpClient, httpResponse) :
  print("In POST-TEST HTTP")

Using variable routes example :

routeHandlers = [
  ( "/edit/<testid>/<testpath>", "GET", handlerFuncEdit ),
  ( ... )
]
def handlerFuncEdit(httpClient, httpResponse, routeArgs) :
  print("In EDIT HTTP variable route :")
  print(" - testid   = %s" % routeArgs['testid'])
  print(" - testpath = %s" % routeArgs['testpath'])

Or direclty with route handler decorator :

@MicroWebSrv.route('/edit/<testid>/<testpath>')
def handlerFuncEdit(httpClient, httpResponse, routeArgs) :
  print("In EDIT HTTP variable route :")
  print(" - testid   = %s" % routeArgs['testid'])
  print(" - testpath = %s" % routeArgs['testpath'])

Using httpClient class in a route handler function :

Name	Function
Get MicroWebSrv class	`httpClient.GetServer()`
Get client address as tuple	`httpClient.GetAddr()`
Get client IP address	`httpClient.GetIPAddr()`
Get client TCP port	`httpClient.GetPort()`
Get client request method	`httpClient.GetRequestMethod()`
Get client request total path	`httpClient.GetRequestTotalPath()`
Get client request ressource path	`httpClient.GetRequestPath()`
Get client request query string	`httpClient.GetRequestQueryString()`
Get client request query parameters as list	`httpClient.GetRequestQueryParams()`
Get client request headers as list	`httpClient.GetRequestHeaders()`
Get client request content type	`httpClient.GetRequestContentType()`
Get client request content length	`httpClient.GetRequestContentLength()`
Get client request content	`httpClient.ReadRequestContent(size=None)`
Get client request form data as list	`httpClient.ReadRequestPostedFormData()`
Get client request as JSON object	`httpClient.ReadRequestContentAsJSON()`

Using httpResponse class in a route handler function :

Name	Function
Write switching protocols response	`httpResponse.WriteSwitchProto(upgrade, headers=None)`
Write generic response	`httpResponse.WriteResponse(code, headers, contentType, contentCharset, content)`
Write PyHTML rendered response page	`httpResponse.WriteResponsePyHTMLFile(filepath, headers=None, vars=None)`
Write file directly as response	`httpResponse.WriteResponseFile(filepath, contentType=None, headers=None)`
Write attached file as response	`httpResponse.WriteResponseFileAttachment(filepath, attachmentName, headers=None)`
Write OK response	`httpResponse.WriteResponseOk(headers=None, contentType=None, contentCharset=None, content=None)`
Write JSON object as OK response	`httpResponse.WriteResponseJSONOk(obj=None, headers=None)`
Write redirect response	`httpResponse.WriteResponseRedirect(location)`
Write error response	`httpResponse.WriteResponseError(code)`
Write JSON object as error response	`httpResponse.WriteResponseJSONError(code, obj=None)`
Write bad request response	`httpResponse.WriteResponseBadRequest()`
Write forbidden response	`httpResponse.WriteResponseForbidden()`
Write not found response	`httpResponse.WriteResponseNotFound()`
Write method not allowed response	`httpResponse.WriteResponseMethodNotAllowed()`
Write internal server error response	`httpResponse.WriteResponseInternalServerError()`
Write not implemented response	`httpResponse.WriteResponseNotImplemented()`

Using route handler function example :

def _httpHandlerTestPost(httpClient, httpResponse) :
  formData  = httpClient.ReadRequestPostedFormData()
  firstname = formData["firstname"]
  lastname  = formData["lastname"]
  content   = """\
  <!DOCTYPE html>
  <html>
    <head>
      <meta charset="UTF-8" />
      <title>TEST POST</title>
    </head>
    <body>
      <h1>TEST POST</h1>
      Firstname = %s<br />
      Lastname = %s<br />
    </body>
  </html>
  """ % ( MicroWebSrv.HTMLEscape(firstname),
          MicroWebSrv.HTMLEscape(lastname) )
  httpResponse.WriteResponseOk( headers         = None,
                                contentType     = "text/html",
                                contentCharset  = "UTF-8",
                                content         = content )

Known mime types (content types) :

File extension	Mime type
.txt	text/plain
.htm	text/html
.html	text/html
.css	text/css
.csv	text/csv
.js	application/javascript
.xml	application/xml
.xhtml	application/xhtml+xml
.json	application/json
.zip	application/zip
.pdf	application/pdf
.ts	application/typescript
.woff	font/woff
.woff2	font/woff2
.ttf	font/ttf
.otf	font/otf
.jpg	image/jpeg
.jpeg	image/jpeg
.png	image/png
.gif	image/gif
.svg	image/svg+xml
.ico	image/x-icon

Default index pages order (for http://hostname/) :

Filename
index.pyhtml
index.html
index.htm
default.pyhtml
default.html
default.htm

Using optional module microWebSocket to connect WebSockets :

File "microWebSocket.py" must be present to activate WebSockets support

Enable and accept WebSockets :

from microWebSrv import MicroWebSrv
mws = MicroWebSrv()                                    # TCP port 80 and files in /flash/www
mws.MaxWebSocketRecvLen     = 256                      # Default is set to 1024
mws.WebSocketThreaded       = False                    # WebSockets without new threads
mws.AcceptWebSocketCallback = _acceptWebSocketCallback # Function to receive WebSockets
mws.Start(threaded=True)                               # Starts server in a new thread

Name	Function
Callback function to receive text message	`ws.RecvTextCallback = func(webSocket, msg)`
Callback function to receive binary data	`ws.RecvBinaryCallback = func(webSocket, data)`
Callback function when connection was closed	`ws.ClosedCallback = func(webSocket)`
Send a text message	`ws.SendText(msg)`
Send a binary message	`ws.SendBinary(data)`
Check connection state	`ws.IsClosed()`
Close the connection	`ws.Close()`

Basic example of callback functions :

def _acceptWebSocketCallback(webSocket, httpClient) :
  print("WS ACCEPT")
  webSocket.RecvTextCallback   = _recvTextCallback
  webSocket.RecvBinaryCallback = _recvBinaryCallback
  webSocket.ClosedCallback     = _closedCallback

def _recvTextCallback(webSocket, msg) :
  print("WS RECV TEXT : %s" % msg)
  webSocket.SendText("Reply for %s" % msg)

def _recvBinaryCallback(webSocket, data) :
  print("WS RECV DATA : %s" % data)

def _closedCallback(webSocket) :
  print("WS CLOSED")

Using optional module microWebTemplate for .pyhtml rendered pages :

File "microWebTemplate.py" must be present to activate .pyhtml pages
Pages will be rendered in HTML with integrated MicroPython code

Instruction	Schema
PY	`{{ py }}` MicroPython code `{{ end }}`
IF	`{{ if` MicroPython condition `}}` html bloc `{{ end }}`
ELIF	`{{ elif` MicroPython condition `}}` html bloc `{{ end }}`
ELSE	`{{ else }}` html bloc `{{ end }}`
FOR	`{{ for` identifier `in` MicroPython iterator `}}` html bloc `{{ end }}`
INCLUDE	`{{ include` pyhtml_filename `}}`
?	`{{` MicroPython expression `}}`

Using {{ py }} :

{{ py }}
  import machine
  from utime import sleep
  test = 123
  def testFunc(x) :
    return 2 * x
{{ end }}

Using {{ if ... }} :

{{ if testFunc(5) <= 3 }}
  <span>titi</span>
{{ elif testFunc(10) >= 15 }}
  <span>tata</span>
{{ else }}
  <span>I like the number {{ test }} !</span>
{{ end }}

Using {{ for ... }} :

{{ for toto in range(testFunc(3)) }}
  <div>toto x 10 equal {{ toto * 10 }}</div>
  <hr />
{{ end }}

Using {{ include ... }} :

{{ include myTemplate.pyhtml }}

Example of a .pyhtml file :

<html>
  <head>
    <title>TEST PYHTML</title>
  </head>
  <body>
    <h1>BEGIN</h1>
    {{ py }}
      def _testFunction(x) :
        return "IN TEST FUNCTION %s" % x
    {{ end }}
    <div style="background-color: black; color: white;">
      {{ for toto in range(3) }}
        This is an HTML test...<br />
        TOTO = {{ toto + 1 }} !<br />
        {{ for toto2 in range(3) }}
          TOTO2 = {{ _testFunction(toto2) }}
        {{ end }}
        Ok good.<br />
      {{ end }}
    </div>
    {{ _testFunction(100) }}<br />
    <br />
    {{ if 2+5 < 3 }}
      IN IF (1)
    {{ elif 10+15 != 25 }}
      IN ELIF (2)
    {{ elif 10+15 == 25 }}
      IN ELIF (3)
    {{ else }}
      IN ELSE (4)
    {{ end }}
  </body>
</html>

😉 Author

Jean-Christophe Bos (:fr:)

GitHub: @jczic
Email: jczic.bos@gmail.com
Profil: LinkedIn
Music: SoundCloud Spotify YouTube

By JC`zic for HC² ;')

Keep it simple, stupid 👍

jczic/MicroWebSrv