README.md 2.58 KB
Newer Older
Stavros Korokithakis's avatar
Stavros Korokithakis committed
1
espota-server
Stavros Korokithakis's avatar
Stavros Korokithakis committed
2
3
4
5
6
7
8
=============

espota-server is an HTTP server that can hold firmware for flashing with the
ESP8266 Arduino firmware. It's useful when you have many ESP8266-based devices
in the field and want them to download their own firmware to update themselves,
rather than you having to push firmware to each one separately.

9
10
11
12
13
The main difference between the espota-server and any other HTTP server is that
it only serves firmware to the device if there's a newer version of the firmware
available. If there's no newer version, it just responds with a "no new version"
and the device goes on its merry way.

Stavros Korokithakis's avatar
Stavros Korokithakis committed
14

Stavros Korokithakis's avatar
Stavros Korokithakis committed
15
16
17
Installation
------------

Stavros Korokithakis's avatar
Stavros Korokithakis committed
18
19
20
21
To install espota-server, just compile it if you have Rust installed, or get the
latest compiled binary from [the nightlies
page](https://gitlab.com/stavros/espota-server/pipelines) and drop it somewhere
on your `PATH`.
Stavros Korokithakis's avatar
Stavros Korokithakis committed
22
23


Stavros Korokithakis's avatar
Stavros Korokithakis committed
24
25
26
27
28
How it works
------------

It's pretty simple, just follow these steps:

Stavros Korokithakis's avatar
Stavros Korokithakis committed
29
1. Make sure you're [using the HTTP
30
OTA](https://github.com/esp8266/Arduino/blob/master/doc/ota_updates/readme.rst#advanced-updater)
Stavros Korokithakis's avatar
Stavros Korokithakis committed
31
32
library in your code, with a firmware URL like
`http://myserver:36942/projectname` (where `projectname` is your project's
Stavros Korokithakis's avatar
Stavros Korokithakis committed
33
name).
Stavros Korokithakis's avatar
Stavros Korokithakis committed
34
35
2. Run the espota-server somewhere.
3. Drop a file called `projectname-version.bin` in the directory where you ran
Stavros Korokithakis's avatar
Stavros Korokithakis committed
36
37
38
the server. Not necessarily the directory where the server *binary* is located,
just where you ran the server. For example, this file should be called
`espota-100.bin`.
Stavros Korokithakis's avatar
Stavros Korokithakis committed
39
4. That's it! Whenever your device attempts to update its firmware, the server
Stavros Korokithakis's avatar
Stavros Korokithakis committed
40
41
42
43
44
45
will respond with a firmware file *only* if there's a file of the same or
a later version in the directory. For example, if a device on version 8 requests
an update, and versions 7 to 22 are available on the server, the server will
respond with version 22. Of course, this means you only need to keep one file
from each project on the server at any time.

Stavros Korokithakis's avatar
Stavros Korokithakis committed
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

NoFUSS protocol
---------------

The server implements the NoFUSS protocol, so you can use it to update
ESPurna-based devices. To get it working, just go to your NoFUSS section
in ESPurna and enter your server's address with the /nofuss path:

http://myserver:36942/nofuss

The firmware files need to be named DEVICE_NAME-1.2.3.bin. For example, my
Sonoff Basic identifies itself as ESPURNA-SONOFF_BASI, so my firmware is
named `ESPURNA-SONOFF_BASI-1.13.2.bin`. If the firmware update fails, just
make sure you've named your files properly and put them in the directory
espota-server starts up in. That's it!

Miscellanea
-----------

Please send pull requests/comments/issues if you have any. That is all.
Stavros Korokithakis's avatar
Stavros Korokithakis committed
66
67

-- Stavros