[App][Pro] Micro Web Server

Micro Web Server

This app turns your Homey into a basic WebServer for your local network.
large

App Store: Micro Web Server
Frequently Asked Questions
Change Log

Supported Languages

:uk: English
:de: German

What? Yes, a WebServer!

There are some use cases where you simply do not want to run another device just to serve a few resources by http.
The app runs a WebServer locally on Homey. This WebServer is not reachable from Internet.
You can use it to host basically any resource you need in reach on your local network. Like a sound file used by another app. Or a full web page even.
Got your own Homey Dashboard written in html and javascript? Let it be served by home itself.

Warning and Disclaimer

Whilst you could basically make the Homey hosted WebServer public on the internet using port forwarding, I highly recommend not to do that. The app is not meant to serve tons of requests from random people.
Also, I am not responsible for the content you are hosting with it, nor for any possible harm one could do to your Homey by abusing it.

Getting Started

To get started, go into the app settings and start the integrated ftp server. Whilst the ftp server is running you can manage the content of your Homey WebServer with basically any ftp client.

Step 1 - Getting Ready for File Uploads

First thing to do after installing is provide some content to be hosted.
To get files onto the Homey we need to start the ftp server of the app. For security reasons it is not running by default.
Open the settings of the app. It should look somewhat like this:
image

After the ftp server is started you should see the ftp address:
image

Step 2 - Connect The FTP Client

Upload your files. Am using FileZilla here as it has proven to work nicely.
Open FileZilla and connect using the hostname shown after ftp:// (or your Homey’s IP) for the Host setting. The default port is 5081 and for login you need to use anonymous authentication:
image
And connect.

Step 3 - Upload Files and Test

After uploading the files you can address them by using the http address shown on the app’s settings page.
Let us assume you just uploaded a giggle.mp3 file. The address would be: http://homey-YourHomeyId:5080/giggle.mp3

About Directories

You can create or upload directories as well. If you open a directory url in your browser instead of pointing to a dedicated file, the app will automatically look for an index.htm or index.html file. Other default index files are currently not supported.

Available Flowcards

Triggers

A WebTrigger was received

WebTriggers are basically WebHooks which are available, by this WebServer, on your local network only.

Arguements

  • ‘Respond to Trigger Name’ defines the name of the trigger to react to.

Tokens

The WebTrigger can carry up to 5 payloads which are made available as tokens to the flow being run. Each payload as 3 representations as follows:

  • ‘Trigger Data # (as text)’
  • ‘Trigger Data # (as number)’
  • ‘Trigger Data # (as boolean)’

In addition the trigger name is available in the flow as text value:

  • ‘Trigger Name’

Usage

The WebTriggers are basic HTTP GET requests sent to the WebServer.
URL Example: http://homey-YourHomeyId:5080/webTrigger?name=MyTrigger&data1=MyTriggerData
Please note that the URL parameters are case sensitive.
The parameter ‘name’ defines the trigger name. It is the name you enter as arguement in the flowcard. The ‘data’ (data, data1, data2, data3, data4, data5) parameters are optional. The parameter ‘data’ is just an alias for ‘data1’.

An advanced WebTrigger was received

WebTriggers are basically WebHooks which are available, by this WebServer, on your local network only.

Arguements

  • ‘Respond to Trigger Endpoint’ defines the endpoint of the trigger to react to. The base path is ‘/webTriggerAdv/’, so you can define as many endpoint as you like. Examples: /webTriggerAdv/MyTrigger, /webTriggerAdv/MySpecialTriggers/Trigger1, 

  • ‘Optional: Respond to specific method only’: By default the trigger card responds to any request (GET, PUT, POST; DELETE, PATCH) send to your endpoint. But you can optionally limit it to listen for a specific method only.

Tokens

The advanced WebTrigger provides access to following data of the request:

  • ‘Trigger Endpoint’ (text) - The endpoint name after /webTriggerAdv/.
  • ‘Method’ (text) - The HTTP method used.
  • ‘Request has Body’ (boolean) - Whether the request has a body data.
  • ‘Request has Json Body’ (boolean) - Whether the request has a json data body available.
  • ‘Json parsing error message’ (text) - This field defaults to ‘No Error’. It will hold the error message if the requests body could not be parsed to a json object.
  • ‘Raw trigger payload data’ (text) - The raw data object of the trigger flowcard. You could already use this but there is an action flowcard for advanced flows which provides you with easy access to the triggers data.

Usage

The WebTriggers are basic HTTP GET requests sent to the WebServer.
URL Example: http://homey-YourHomeyId:5080/webTriggerAdv/aTriggerName?queryValue=something&someOtherQueryValue=somethingElse
Please note that the URL parameters are case sensitive.

Actions

Get data from advanced trigger payload

This action is available in advanced flows only and provides easy access to any data received from the webhook.

Arguements

  • ‘Trigger payload token to use’: The flow token (Raw trigger payload data token) provided by the trigger flowcard to be used.
  • ‘Data source’: Where to look for data. This can either be the request’s header fields, the url query parameter fields or the request’s json body data.
  • ‘Data Field to extract’: The name or path of the data field to extract. In case of the headers (mind that header field names often are lower case automatically) and url query fields you just use the name of the field here. For the json body you can address nested fields with the dot syntax (Example: MyObject.MyObjectValue). You can also access individual array elements using the bracket index syntax (Example: MyArray[23]).

Tokens

The card emits flow tokens for the extracted field:

  • ‘Trigger Data (as text)’
  • ‘Trigger Data (as number)’
  • ‘Trigger Data (as boolean)’

Usage

Here is a very basic advanced flow example to give you a better idea of how it works:


This flow would now react to a request like this:
image

8 Likes

Frequently Asked Questions

Q: Can it host a local copy of homeydash.com?
A:: Yes. This has been tested successfully.

Q: Which FTP client should I use?
A:: Whilst it is supposed to work with any ftp client, some seem to cause problems. It has been tested successfully with FileZilla.

Q: WinSCP does not list the files on Homey?
A:: WinSCP was reported to be working with certain settings:
File Protocol: FTP
Encryption: No encryption
Host name: IP of Homey
Port number: 5081
Login: Use “Anonymous login”
Disable “Passive mode” in advanced settings for the connection.

Q: The URL shown on the app settings page is not working with Chromecast?
A:: I am not sure why a Chromecast device would not resolve it. But try using your Homey’s LAN IP instead of the host name. This has proven to work as well. Like http://192.168.2.55:5080/aDirectory/giggle.mp3

Q: My mp3 file is not playing when I cast it using the cast audio url card of the chromecast app.
A: This is a known issue. I do not know why Athom’s chromecast app behaves weirdly there. But it will work if you use the cast website card instead.

Q: The FTP Server allows anonymous access, isn’t that pretty insecure?
A:: I did that for ease of use. However, the ftp server is not started automatically. Simply restart the app and no one can access it anymore.

Q: Does it support https?
A: No. This is not planned to be supported either.

Q: Can I run php scripts and things like that?
A: No. The WebServer only serves static files (HTTP GET is handled only). If you need such fancy stuff you might as well consider running a full blown WebServer on your lan instead. However, starting with v1.2.2 you can send HTTP GET requests to the WebServer to trigger flows.

Change Log

v2.2.0

  • Added: Advanced webhook data retrieval flowcard now supports array access as well.

v2.1.1

  • Added: Advanced webhook support.

v2.0.6

  • Homey Pro 2023 compatibility update. (again :angry: )

v2.0.5

  • Fixed: WebTrigger compatibility for Homey Pro 2023.

v2.0.4

  • Homey Pro 2023 compatibility update.

v2.0.3

  • Fixed: Edge case crashes.

v2.0.2

  • Updated: Added formatted card titles.

v2.0.1

  • Updated: Advanced flows compatibility update.

v2.0.0

  • Updated: Supported mime types been updated.
  • Updated: The app has been migrated to Homey App SDK v3.

v1.5.0

  • Updated: Supported mime types been updated.
  • Added: App setting to optionally auto launch the ftp service on app startup.

v1.4.0

  • Updated: Supported mime types been updated.
  • Updated: FTP greeting message now includes the app version.
  • Updated: Minor changes to the FTP server instancing to be more explicit on the interface to listen on.

v1.3.0

  • Updated: Supported mime types been updated.

v1.2.3

  • Fixed: A potential app crash issue when a certain error condition is met.
  • Updated: Sent HTTP headers are now more compliant to common standards used.

v1.2.2

  • Fixed: Now the WebServer returns proper HTTP status codes for unsupported request types.
  • Update: Upgraded to new nodejs URL api. For compatibility reasons the new version now requires Homey firmware version 4.2.0 or higher.
  • Added: Basic WebTrigger support.

v1.1.0

  • Fixed: App crashed when no index.htm/index.html file was found when calling a directory. Returns now a proper HTTP 404 as you would expect.
  • Fixed: App crashed when HTTP port was already in use or blocked.
  • Fixed: Sending url rewrites for directories without trailing slash.
  • Changed: Service startup errors (if any) are now shown on the settings page along the status of the service.
  • Changed: The start ftp server command now gives feedback when triggered by hiding itself.
  • Added: Proper handling of query data in URLs.

v1.0.1

  • Rebranding

v1.0.0

  • Initial Release

Initial version has been released to the App Store today! Enjoy.

1 Like

Works like a charm with FileZilla. Have also tested CuteFTP but could not connect with it.
Nice job, well done!

1 Like

Question:
Install app and add 100MB of files to the micro web server.
Then delete app, what happens to the uploaded files?
Will they stay on the server or will they be deleted?

The files are stored in an app context specific filestore. So I would assume that this storage is wiped when you explicitly uninstall the app. Anything else could be considered as a bug by Athom I guess :smiley:

1 Like

Tried this today. Works fine on Sonos via hostname and ip address. But doesn’t work on chromecast devices (smart clock, home mini and chromecast). Tried the hostname and ip address.
Error:
image

Hi @PaN13k,
What did you try exactly? Can elaborate a bit more on what you are trying to do? And which card raised this error?

I tried to cast a sound url:

Oha, you are right @PaN13k.
I used it successfully with my Home Mini but my flow is now broken as well. But it seems like this is more an issue with the Chromecast app or the Chromecast firmware there. The URL works properly still. Guess I will test this myself now and annoy Athom about it.

Exactly. The URL also works here. Either via de Sonos speakers or directly via de browser. Thanks in advance.

My situation could be completely different but this is an observation from my ONVIF app. I store the last motion event image in what I believe is an app context filestore (not the standard image area). If I remove the app and then reinstall it, the last image is still there. To make sure it is cleaned up, I delete the image in the device onDeleted() event and that seems to solve my problem.
Just food for thought and I’m not saying you are wrong. A bug by Athom, really? :wink:

1 Like

Thanks to @PaN13k for bringing to attention that the cast audio url of Athom’s chromecast app is not working when passing in a Homey Micro WebServer URL. I don’t know why the chromcast app started to behave wierd there recently.
Anyone having this issue should replace the cast audio url card with the cast website card, giving the very same URL to the mp3. That will do the trick.

2 Likes

I have a problem with my FTP connection; I can log in but do not get a directory listing and cannot upload any files. I tried several FTP programs, with the following output:

dos ftp command:
ftp> open 192.168.1.102 5081
Connected to 192.168.1.102.
220-Micro Web Server
220 Features: a .
530 Command requires authentication
User (192.168.1.102:(none)): anonymous
230 User logged in, proceed
ftp> dir
200 The requested action has been successfully completed
425 No connection established
ftp>

Filezilla:

Status: Connecting to 192.168.1.102:5081

Status: Connection established, waiting for welcome message

Status: Insecure server, it does not support FTP over TLS.
Status: Logged in
Status: Retrieving directory listing

Command: PWD
Response: 257 “/”
Command: TYPE I
Response: 200 Switch to “binary” transfer mode.
Command: PASV
Response: 502 Command not supported
Command: PORT 192,168,1,100,249,11
Response: 200 The requested action has been successfully completed
Command: LIST
Response: 425 No connection established
Error: Failed to retrieve directory listing

I’ve been trying to find a solution but I’m running out of ideas. I would really appreciate any suggestion that you may have.

Hi @Chris_Peters,
have you tried using FileZilla, yet?
Also, can you please submit me a diagnostics report for the app so I can check on your logfile? In your Homey app go to More -> Apps -> Micro WebServer -> Little Gear (up right on Android) -> Submit Diagnostics report. Please include your forum name in the report message for reference.

Hi,

thanks for the quick reaction.

The FilleZilla log is at the bottom of my original message.

I have submitted the diagnostics report; the code is: 0fc322a7-37c5-41f2-a7ee-69594bab919d

Chris

Hi again @Chris_Peters,
I assume the 192.168.1.100 is the system you are trying to connect from?
The good news, the ftp server part seems run properly.
The bad news part)
The server says it is getting timeout error while trying to write the result back to the client. Do you have any special desktop firewall software in place maybe which could be interferring?

I have windows firewall, so that could be a problem. I just don’t know how to fix that

@Chris_Peters hmm am also using the buildin win firewall without issues though. I will have a closer look at it after work. Let me know if you find anything in the meantime.