Sie sind auf Seite 1von 92

Hackitt and Bodgitt ESP-12 Software and

Hardware
Last update February 07, 2017

The software described in this manual currently uses Espressif SDK 2.0 from the
Espressif forum.
It is obtainable either as ROMS which can be flashed to an ESP-12 module or as a
complete project which works in the Windows Unofficial Development Environment.
This may change as updates to the SDK are made available by Espressif (ESP8266
designers). All information and examples can be found on the blog mentioned in
here.

Home Control 2017 software Page 1


http://tech.scargill.net
Home Control 2017 software Page 2
http://tech.scargill.net
Preface
This document explores code written by Peter Scargill (with considerable help from
Aidan Ruff and others too numerous to mention - and of course with open-source
libraries and the Espressif SDK) for the ESP8266 and all of this represents many,
many months of work1.
The software started off life as an extension of TUANPMs MQTT demonstration
software but rapidly developed from there. Over time I added more and more of my
own code and of course bits and pieces from around the web as I learned more and
more about the ESP8266 one of the most useful and best value WIFI modules in
the IOT world. The code is tested to work with Aidan Ruff's various boards detailed
in the blog at http://tech.scargill.net - Article "Home Control 2016" and the newer
boards used in the Nextion project (all on the blog) which incidentally won 2 nd place
in the first ESP8266.com awards in April 2016. Aidans board designs are usually up
on the blog or you can talk to him directly.
In fact the software will work with just about any ESP-12-based board or similar
but if it doesnt work on any other board, you should seek assistance from the
designer(s) of the board. It CAN be made to work with older boards with smaller
FLASH space but I highly recommend either abandoning older designs or
upgrading the Flash to 4Mbytes (details about that in the blog at
http://tech.scargill.net). At some point the software will exceed the capacity of the
original 512K ESP-01 type boards without modification.

1
This software is free and technically unsupported..

Home Control 2017 software Page 3


http://tech.scargill.net
Contents
Hackitt and Bodgitt ESP-12 Software and Hardware...................................................1
Preface.................................................................................................................... 2
Contents.................................................................................................................. 3
In a Nutshell............................................................................................................ 8
Automatic responses............................................................................................. 12
Node-Red and MQTT.............................................................................................. 13
Node-Red........................................................................................................... 13
MQTT.................................................................................................................. 14
The LED Clock....................................................................................................... 15
The LCD/OLED Display.......................................................................................... 16
Now the PARALLEL LCD!..................................................................................... 18
And finally the OLED........................................................................................... 18
Commands............................................................................................................ 21
Queries.................................................................................................................. 22
Boards................................................................................................................... 22
General MQTT/Serial Control Format.....................................................................23
List of Commands.................................................................................................. 24
adc..................................................................................................................... 24
ads1115............................................................................................................. 24
attrib.................................................................................................................. 25
calibrate............................................................................................................. 25
clock................................................................................................................... 26
cpu_freq............................................................................................................. 26
dawn.................................................................................................................. 27
debug................................................................................................................. 28
desc................................................................................................................... 30

Home Control 2017 software Page 4


http://tech.scargill.net
dusk................................................................................................................... 30
electrodragon..................................................................................................... 31
enable13............................................................................................................ 31
enable14............................................................................................................ 32
enable16............................................................................................................ 32
ext...................................................................................................................... 33
flashsize............................................................................................................. 33
gettime............................................................................................................... 34
gy30_init............................................................................................................ 34
gy30_read.......................................................................................................... 35
heap................................................................................................................... 35
hitachi................................................................................................................ 36
hightemperature................................................................................................ 36
hsv..................................................................................................................... 37
humidity............................................................................................................. 38
i2c...................................................................................................................... 39
i2c_check........................................................................................................... 40
id........................................................................................................................ 40
in14.................................................................................................................... 41
in_2bounce......................................................................................................... 41
in_14bounce....................................................................................................... 42
in14_count......................................................................................................... 42
in2_count........................................................................................................... 43
invert.................................................................................................................. 43
invertset............................................................................................................. 44
invertreset.......................................................................................................... 45
kelvin.................................................................................................................. 46

Home Control 2017 software Page 5


http://tech.scargill.net
led_timer............................................................................................................ 46
mist.................................................................................................................... 47
mqtt_host........................................................................................................... 47
mqtt_pass.......................................................................................................... 48
mqtt_port........................................................................................................... 48
mqtt_user........................................................................................................... 49
nano................................................................................................................... 49
ota_host............................................................................................................. 50
ota_port.............................................................................................................. 51
otaupdate........................................................................................................... 51
out0.................................................................................................................... 52
out4.................................................................................................................... 53
out5.................................................................................................................... 54
out12.................................................................................................................. 55
out13.................................................................................................................. 56
out14.................................................................................................................. 57
out15.................................................................................................................. 58
out16.................................................................................................................. 59
xport.................................................................................................................. 60
pass.................................................................................................................... 61
pass2.................................................................................................................. 61
pca9685............................................................................................................. 62
polling_interval................................................................................................... 63
port2out............................................................................................................. 63
pwm................................................................................................................... 64
pwmhsv.............................................................................................................. 64
rainbow.............................................................................................................. 65

Home Control 2017 software Page 6


http://tech.scargill.net
rebootnow.......................................................................................................... 65
reset................................................................................................................... 66
reset_config........................................................................................................ 66
rgb_ind............................................................................................................... 67
rgb_lcd............................................................................................................... 67
rgb...................................................................................................................... 68
rgbgo.................................................................................................................. 69
rgbinstant........................................................................................................... 69
rgbstop............................................................................................................... 70
rgbset................................................................................................................. 70
rgbstart /add/stop.............................................................................................. 71
rgbperm............................................................................................................. 73
romswitch........................................................................................................... 74
scan.................................................................................................................... 74
set_serial............................................................................................................ 75
si1132_visible, uv and ir..................................................................................... 76
sonoff................................................................................................................. 77
ssid..................................................................................................................... 77
ssid2................................................................................................................... 78
swap................................................................................................................... 78
temperature....................................................................................................... 79
temp_type.......................................................................................................... 79
temperature_port............................................................................................... 80
time.................................................................................................................... 80
timeout_set........................................................................................................ 81
timeout_clear..................................................................................................... 81
to_nextion.......................................................................................................... 82

Home Control 2017 software Page 7


http://tech.scargill.net
to_serial2............................................................................................................ 83
uptime................................................................................................................ 83
voltage............................................................................................................... 84
warning.............................................................................................................. 84
web_setup.......................................................................................................... 85
wifi_button......................................................................................................... 85

Home Control 2017 software Page 8


http://tech.scargill.net
In a Nutshell

So the basic idea here is that you would have a number of ESP-8266-based boards
working alongside an inexpensive central controller could be a Raspberry Pi2/3 or
similar setup with MQTT and Node-Red (the blog also links to a script (see blog) to
install Node-Red, SQLITE, MQTT) and various tools onto a Pi2 or 3 with minimum
effort), this software communicates via serial or (mainly) MQTT commands over WIFI
to control a range of ESP8266-based, reliable devices with facilities including:

12v RGB LED strip via 3 MOSFETs with soft fade from one state to the next
Serial LED strip (tested up to 300 RGB serial LEDs) with soft fade from one
colour to the next
HSV version of above (more intuitive)
Kelvin temperature shade version of above from 1000-4000K (sad lamp?)
LED clock using 60 serial LEDs
General serial LED output to any of the output pins
A relay (for example) output with ON/OFF and timer operations covering
minutes or seconds (the latter might be useful for watering systems, for
example)
Various temperature/humidity/pressure chips including:

Home Control 2017 software Page 9


http://tech.scargill.net
o Dallas DS18b20 temperature
o DHT11, DHT22 temperature and humidity
o BMP280 - temperature and pressure
o BME280 temperature, humidity and pressure
Two Debounced inputs (gpio2 and gpio14) which can also read a change
count and be polled as well as MQTT broadcast on change
Support for both a simple LED indicator or a colour-coded RGB serial RGB LED
on the board (gpio13)
RTC software updated on power-up/logon via MQTT and at regular intervals
Nextion Serial displays can form a WIFI Touch Display
i2c expansion on gpio4 and gpio5. There is software to handle a Hitachi-style
LCD both in simply 6-wire parallel mode or i2c via a cheap port expander,
drivers for SEEED displays, 16-channel PWM control and simple port
expansion, 16-bit ADC, 2 types of temperature/pressure/humidity sensor and
a complete NANO-based peripheral with more on the way
Dual access-point handling for reliability and an awful lot more see the list
of instructions
Early signs of SPI extensions experimental SPI display (using ports 13 to 16)
One of the accompanying board designs on the blog (you can use this software with
any generic ESP-12 board) is able to handle either a mains power supply OR a DC-
DC convertor and uses the ESP-12, ESP-12E or ESP-12F modules.
The software needs the 4MB Flash of the likes of the ESP-12. It will work with older
chips but no OTA (over the air updates) in the future the code may no longer work
with older boards due to insufficient FLASH but these can generally be upgraded
with a cheap FLASH chip and a fine soldering iron. I have blogged how to do this.
See http://tech.scargill.net/esp8266-home-control-update/
There is an on-board 3v3 linear regulator on our board designs to ensure a smooth
supply to the ESP. Extensive experience suggests that the software is rock-solid
however no guarantees. The author has 2 houses both of which rely on several of
these boards working 24-72 and they are in two different countries so popping in
to fix is not an option.
In order for this all to work correctly, the board at power up will try to log into a
general WIFI access point clearly you will need to alter the ID either by serial
commands or by WIFI setup.

2
That does not mean I accept any liability for the software or hardware which is generally
designed for our own use and made freely available to other on which to experiment and
enjoy.

Home Control 2017 software Page 10


http://tech.scargill.net
When I set up my boards - I send this serially (115Kbaud) using my terminal
program.
{ssid:"wififorus"}
{ssid2:"wififorus"}
{pass:"xxxxxxxxxxx"}
{pass2:"xxxxxxxxxxx"}
{mqtt_host:"192.168.1.19"}
{mqtt_pass:"yyyyyyyyyy"}
{rgb_ind:0}
{reset}
There are other commands you might want to check to do with deciding which input
in is used for web programming and whether GPIO2 is an input or an output.
{temperature_port:2} // if you want to use port 14 use the relevant command.
You must set your access point up, with or without a password. There is a second
access point entry for fall-over. Make the second one the same as the first if you
only wish to use one access point.
You should then set up the address and optional port, username and password of
your MQTT server. For my own purposes I use an MQTT broker with username and
password.
This will get you started the board will log into your access point, then it will
connect to your MQTT server and it will try to log in. It will do this repeatedly,
handing over its ID and description via MQTT until it gets a response.
It is possible to respond using MQTT but it is a lot easier to let my Node Red node
handle logging in and responding for you. The node can be installed as npn install
node-red-contrib-esplogin.

My setup is shown here the incoming MQTT node is subscribed (despite the
general turm login to esplogon. Thats simple esplogon with an o. The
ESP8266 units publish to this topic on power-up.
See http://flows.nodered.org/node/node-red-contrib-esplogin for the login node and
for my general purpose timer node

Home Control 2017 software Page 11


http://tech.scargill.net
http://flows.nodered.org/node/node-red-contrib-bigtimer
The only output on that yellow login node you need to use is the first one and that is
fed to an MQTT output no info necessary other than the correct MQTT setup the
rest is optional speech output, log file output and sqlite output.
With this in place, the boards should log in get the time and more from the yellow
esplogin node and thats about it. The same node will refresh them every day
automatically with the time or any time they log in (after a power failure for
example).
Right now this setup typically runs on a Raspberry Pi or PC currently playing with
the idea of running Node-Red and MQTT on an Android mobile phone or tablet.

Home Control 2017 software Page 12


http://tech.scargill.net
Automatic responses
Certain MQTT messages are send out automatically from the boards and can be
read without having to actually make requests of the board.
If a DHT11 or DHT22 sensor is selected {temp_type:x} (for values of x read the
relevant command) then readings are currently taken every 30 seconds and stored
in variables which can be polled at any time however, MQTT messages are also
automatically generated.

If using a Dallas temperature chip (which does not do humidity) then only the
temperature message is generated. Output is in degrees C (in case you were
wondering if it was very cold here when I took that reading).
AND NOW {pressure} if using the BME280 chip on I2c on GPIO4 and 5
GPIO14 is normally used as an input and can be polled. However a debounced
output also generates an automatic message on change:

Yes, this board is called fred {id:fred}


GPIO2 can do the same but it is also used for a variety of other purposes such as
web-setup pin and temperature sensing pin. To enable GPIO2 to act as another
debounced input pin you should first ensure that it is not being used for other
purposes.
The relevant commands are {temperature_port} and {temp_type}
For example lets say you want automatic readings from GPIO2 (typical) using a
DHT22 chip. Set {temperature_port:2} and {temp_type:1}
From there on you may see this when monitoring MQTT in my case the pergola.
if Node-red subscribes to pergola/fromesp/auto_temperature and
pergola/fromesp/auto_humidity it will receive this information regularly.

Home Control 2017 software Page 13


http://tech.scargill.net
Node-Red and MQTT
You will see Node-Red and MQTT referred to extensively in here so what better
place to tell you what they are and why you should be interested.

If you dont understand MQTT read the following section first better yet Google
and become familiar with the basics of MQTT it is simple and it IS worth knowing
about.

Node-Red
When I first took an interest in Home Control having developed systems
independently in the past (Appcon in the 1980s) I wanted to use a standard - but
there are so many of them some are really restrictive or expensive to use if you
are a DIY type. Many had a large learning curve for even the simplest things and
Im sorry Im not paying 30 to turn a light on.
After many false starts, it began to make sense to use an inexpensive, powerful tool
such as the Raspberry Pi 2 or 3 to control the house using the cheapest end-
controllers I could get or make. It turns out that the ESP8266 in its various forms is
the cheapest and I think best solution and that is WELL covered in the blog so I
wont develop that further here.
Software was not as straight forward lots of options but I like to do my own thing
and understand what Im doing so I took a chance when the guys at IBM came up
with Node-Red. This runs no NodeJS which Id also not heard of. In a nutshell an
extremely powerful yet extremely easy to use visual interface using drag and drop
but allowing you to program, running on the likes of the Pi with other platforms
including the web, Windows PCs and more.
To get a feel for the simplicity of Node-Red I can think of no better example than
https://fred.sensetecnic.com/ - it is a little out of date now as UI has been
replaced by the vastly superior dashboard (currently at version 2) but once you
sign up for free you can start playing with Node-Red for free and with no installation.
Alternatively Raspberry Pi now supports Node-Red by default. I have a setup script
described on the blog to set up a Raspberry Pi. Really there are links to
documentation and examples on that site. A good starting point. There are others.
Once set up for example monitoring an input on a board and sending yourself an
email if something changes or tweeting or putting a timer on an output are all
trivial and by and large visual. If you are used to traditional line by line
programming it can be an eye opener and Node-Red is very reliable.

Home Control 2017 software Page 14


http://tech.scargill.net
MQTT
The general idea is simple a Broker or server software lets you send messages
via the broken to any other MQTT client on the system trivial to use - via the
concept of a topic and a payload think of them as an address and message
all in simple text.
Fast and efficient, communication is made in this project either serially by sending a
command to the board or by sending a topic and a payload (with the command in it)
via MQTT over WIFI. MQTT is ideal for IOT applications because it is simple, easy to
understand and largely free.
You can install an MQTT broker or server on a Raspberry Pi for example or there
are public ones its a big subject but keep in mind that at the end of the day it is
not complicated- the codes below are my own not some complex part of MQTT. In
the simplest case you send a TOPIC which is a text-based field and a PAYLOAD
which is a text-based field. The topic is to identify where it must got to the payload
is whatever you want. A unit subscribes to a topic or topics and the broker both
accepts messages and makes sure they get to who theyre supposed to. So the
broker, wherever it is located helps form a comms network really WAY easier to
use than explain.
To become familiar with MQTT you can mess with MQTT by using a public broker
and the free MQTT-SPY (client). A couple of machines running MQTT-SPY can send
messages to each other via the broker. It is even fun once you grasp it. Certainly it
does not need to be any harder than sending text messages. A client listens for a
particular topic or topics. There are many explanations of MQTT on the web.
Node-Red and MQTT Together
Together, Node-Red and MQTT make a powerful tool any device on the system can
talk to Node-Red or to any other device.. Personally rather than having a million
protocols I like to make everything talk to Node-Red via MQTT then it can decide
what to send out to whom. With the many nodes available in Node-Red including
my own BIGTIMER and others what you can do is largely down to your imagination.
I usually add SQLITE into the mix as a simple database for logging information that
is not too heavy on writing (excessive writing is not good for SD-based boards)

Home Control 2017 software Page 15


http://tech.scargill.net
Home Control 2017 software Page 16
http://tech.scargill.net
The LED Clock
This started as a gimmick but it REALLY looks nice.
A simple command {clock:0} for example will start a serial RGB LED clock on GPIO0
and this will be maintained through power cycle. The clock knows the time because
the central server (Pi or similar) sends the time in the logon system. The clock uses
serial LEDs and needs 60 of them. You can do this with some RGB serial LED strip
or you can buy a 60 LED ring usually in the form of four quadrants. The likes of
AdaFruit sell them but on Ebay, Electronics_Lee sells them for less.
http://www.uctronics.com/ring-wall-clock-60-ultra-bright-ws2812-5050-rgb-led-lamp-
panel-for-arduino.html?___SID=U
Around 12 for the entire ring you just need to solder the bits together. Ebay sell
plastic disks as well!!
So typically you are looking at 5v, signal and ground Ive used variable brilliance
lighting to give a wide bar for hours (5 LEDS) and the single LED is seconds All
looks lovely in the dark!
To end this set the number to 255 i.e. {clock:255}. Dont set the clock to use an
input.

Home Control 2017 software Page 17


http://tech.scargill.net
Home Control 2017 software Page 18
http://tech.scargill.net
The LCD/OLED Display
Ive been messing with I2c and included some support for a
2-line or 4-line LCD and now also a parallel version.
So what youre looking at on the right the glowing thing at
the top is an FTDI basically there for me to program with
and to provide a little power. The blue prototyping board is
in fact a test board - an ESP-12 with a regulator running my
software as described in here.
The red thing in the middle is an i2c expander cheap
basically i2c in on 2 wires (it has pullups) 8 IO lines. Im
using them only as IO and Im only using 6 of them the top
4 data lines, enable and the control line.
Least significant bit is enable, next is the control line, top 4
are MSB data lines on the LCD.
Essentially from either MQQT or serial you fire a command
at the ESP board and text appears on the LCD. There are of
course some set up and control commands and Ive
incorporated them into a string.
In the example you see here, this is the string I fire at the
display every second from MQTT
Payload: {hitachi:39,"$1MQTT test$2$i$3Time $t$4Date $d"}
Simple enough, device 39 (in this case) and some text with control signals starting
with $

Home Control 2017 software Page 19


http://tech.scargill.net
Here is the list of commands:
$$ - shows a dollar on the screen!!
$S - setup sets up a virgin 20x4 LCD and clears the screen
$s - setup sets up a virgin 16x4 LCD and clears the screen
$c - clear the screen
$1 set the cursor to position 1 line 1
$2 set the cursor to position 1 line 2
$3 set the cursor to position 1 line 3
$4 set the cursor to position 1 line 4
$5 set the cursor to position 9 or 11 line 1
$6 set the cursor to position 9 or 11 line 2
$7 set the cursor to position 9 or 11 line 3
$8 set the cursor to position 9 or 11 line 4
$t - fire out the time
$d fire out the date
$i - fire out the current ip address
$X - clear the current 16 character line
$x - clear a line of 8 or 10 characters (depending on setup)
$o - display the degrees symbol
$l - display left arrow
$r - display right arrow
$b display block-out character
$F and $f - turn the LCD backlight on and off only works if your back panel
support it.
$p and $h temperature and humidity readings assuming you have a sensor
running and wait a couple of mins before using after power up. Note temperature
and humidity readings remain at 0 (zero) until WIFI and MQTT are connected.

Home Control 2017 software Page 20


http://tech.scargill.net
Now the PARALLEL LCD!
Flushed with success at getting my little I2C
enabled 4-line display working, it occurred to me
during an early start to the morning that theres
an even better way for people with no other use for
the output pins. I have therefore reserved device
number 255 to work with the display in PARALLEL.
You need the following (GPIO4/5 reference is correct
for our boards you may or may not need to
reverse these for other boards)

GPIO4 EN
GPIO4 CONTROL/DATA
GPIO12 data 4
GPIO13 - data 5
GPIO15 - data 6
GPIO16 - data 7

You should ground the Read/Write pin on the LCD


and you may wish to consider a resistor from the
contrast pin to ground 150r is generally ok and
some LCDs may require separate wiring for
backlighting (I just took the backlighting A to +5v, K
to ground).
Note that the instant you use this any flashing
light on GPIO13 will stop cant have it both ways

This of course leaves you with GPIO2 and 14 for use


as inputs a thought GPIO2 as temperature sensor
GPIO14 as up/down temperature control.

And finally the OLED


I have the first OLED running one of those little
SEEED OLEDs. Waiting for the AliExpress cheap ones
to turn up but could not resist having a go at an
OLED I had lying around. Commands similar to
Hitachi but no backlight. Have added a g
command for grey level and numbers 0-11 for lines.
Example: {seeed:$s$g3Hello$g11Hello}

Home Control 2017 software Page 21


http://tech.scargill.net
{seeed:"$sHello there$5$i$6temp:$pc$7Hum:$h%$11$t"}

Home Control 2017 software Page 22


http://tech.scargill.net
Experiments
Experiments are just that they cannot be relied on to stay the same or even
continue because they might prove problematic.
My current experiment is the use of an
ILI9340-based display, the cheap ones
from AliExpress etc. at 240*320
resolution. These are REALLY nice for the
price, full colour LCD.
Until recently I could not get these to
work at all on the ESP8266 as any code
for them was for Arduino-based and not
that easy to translate back to C (its a lot
easier the other way around).
In an article youll find on the blog about
a cheap terminal, I discovered some C
code to do a really FAST scrolling VT-100-
subset terminal. This was stand-alone and
so firstly I converted the code to work in
the Arduino environment I have it
running on the Arduino itself.
In one of those mistaken moments I
figured it would be easy to convert to ESP
SPI. Well, it was not and I spent over 2 solid days before I could even clear the
screen. Anyway to cut a long story short it is now working exceedingly well on both
and particularly well on the ESP but beware it uses GPIO 13, 14, 15 and 16 and
hence uses up much of the available useful IO on the board. Still it is VERY fast,
has a nice top line and bottom status line and a scrolling centre region offering a 40
char by 40 line terminal for those with decent eyesight. Command s for cursor,
scrolling and colour are implemented and Ive just added the escape character into
my line parser so it will handle stuff like this.
{ili_set:1}
{ili_text:"\e[35;40mHello there \e[32;40mmate\r\n"}
{ili_status:"All working exceedingly well"}
{ili_title:"\e[37;40mESP8266 Status Monitor"}
{ili_rssi}
The ili_set command if set to 1 will immediately reset the display and enable it to
accept messages this survives power out and the display will automatically

Home Control 2017 software Page 23


http://tech.scargill.net
initialise on power-up. Setting the value to 0 disables the display again through
power cycling.
So then given the unit name of thisone a simple bit of Node-Red directs all MQTT
traffic to the display (along with some colour commands).
tmpPayload=msg.payload;
tmpTopic="\\e[36;40m"+msg.topic+"\\e[32;40m\r\n";
if (msg.topic!="thisone/toesp")
{
msg.topic="thisone/toesp";
msg.payload="{ili_text:\"" + tmpTopic + tmpPayload + "\r\n\"}";
return msg;
}
Ive deliberately stopped traffic for that unit as it ends up in infinite loop
otherwise. For wiring, the LED and power for the board need to go to +3v3, reset
goes either to the ESP8266 reset or via a 4k7 to +3v3. and then GPIO14=SCLK,
GPIO13=MOSI, GPIO15=CS and GPIO16=D/C - MISO (last pin) is not used.
No, the software does not support a whole other range of boards, just this one but
as its one of the cheapest out there thats fine.
The ili_rssi command puts up a rough signal strength for this particular ESP along
with the time but that only works of course assuming you are using my Node-Red
node which updates the boards with the time.
No Ive not tested this extensively thats why its called an experiment up to now
it is working a TREAT and is surviving day-long testing I even took it for a walk
using a battery pack and it survived going out of signal range and coming back in.
Clearly the use of these ports on the ESP8266 stops some other operations but
what a great general purpose MQTT display! Only one font for now the fellow who
modified kind-of-Adafruit driver only included the one Ive just figured out the
format so I may add a larger font for headings etc. at some point.

Home Control 2017 software Page 24


http://tech.scargill.net
Commands
Commands can be sent to an ESP8266 board via 115k serial or via MQTT.
This software specifically:
Given device ID X (a string with no spaces) - the MQTT topic will be X/TOESP
The MQTT message will always be surrounded by {} and a colon separates the
command and the first arguments subsequent arguments use commas. This is all
my choice again not MQTT specific. The format bears a vague resemblance to
JSON.
Why X/TOESP ?? Well, I wanted an easy way for a device to accept messages just
for itself or for EVERYONE. So lets say we call a board fred.
The board subscribes to fred/toesp and toesp (you dont have to worry about this
just give it an ID the software does the rest).
If say the Pi needs it to listen to messages meant for everyone send to topic
toesp If you want to send a message to that board only, send to topic
fred/toesp.
And now to the actual message:
Heres a simple real example:
To turn the relay on (on our original board, attached to GPIO0): {out0:1}
To to turn it off {out0:0}
Simple you can send a message complete with topic over WIFI using MQTT or just
blast the topic followed by CRLF through the serial at 115k baud.
In the list to follow, * indicates information is subsequently stored in FLASH so for
example if you set up a clock you want it to start up after loss of power. Also if you
set an output ON general after a power failure you want it to resume where it left
off. Up to now this FLASH info saving has proven 100% reliable.
Please note: As of Feb 2016 references to OUT0 may go to output 0 or 16 this
is settable by command. This is because we want to reserve GPIO0 not only for
programming but also for WEB setup GPIO0 was only historically used for relays
because of the ESP-01.

Home Control 2017 software Page 25


http://tech.scargill.net
Queries
Queries (i.e. you dont want to do something you just want to return info) have no
argument but end with ? i.e. {time?}
{query?}
Not all commands can be used as queries.

Boards
The software requires an ESP-12 or similar with 4MB of FLASH. Older boards
currently work with no OTA but as the software gets more commands this may not
always be the case.

Home Control 2017 software Page 26


http://tech.scargill.net
General MQTT/Serial Control Format
The general format for commands is:
{command:parameter1,parameter2,parameter3 etc.}
Software supports up to 8 long-integer parameters, any of which might be replaced
as appropriate by one of 2 string parameters. Strings are in quotes, the whole
command in braces, integers can as appropriate be positive or negative.

Home Control 2017 software Page 27


http://tech.scargill.net
List of Commands
The following is a list of commands there are lots of them and there is still room
for more. At some point these will be sorted into alphabetical order

adc
Function:
Returns the value of the ADC
Use: adc
Example: {adc?}
Return: Mqtt adc value. Serial: string containing the ADC value
Query: yes
Stored in Flash: no

ads1115
Function:
Sets up and returns the value of an I2c ads1115 ADC board
Use: ads:integer value
Example: {ads1115:1} to set up input A0 (2,3,4 for the other 3) then {ads1115:0}
to read
Return: Mqtt adc value. Serial: string containing the ADC value
Query: yes
Stored in Flash: no

Home Control 2017 software Page 28


http://tech.scargill.net
attrib
Function:
Set or read the optional attrib string of the board
Use: attrib
Example: {attrib:lamp} or {attrib?}
Return: Mqtt nothing. Serial: string containing the attrib if query or OK
Query: yes
Stored in Flash: yes

calibrate
Function:
To calibrate voltage readings on our original board
Use: calibrate:integer_value
Example: To be completed
Return: Mqtt none. Serial: OK
Query: no
Stored in Flash: Yes

Home Control 2017 software Page 29


http://tech.scargill.net
clock
Function:
60 Serial LED clock
Use: clock:integer_value (port number)
Example: {clock:0} (use {clock:255} to kill the clock)
Return: Mqtt none . Serial: none
Query: no
Stored in Flash: yes
Notes: Attach 60 serial LEDs to the port make sure the time is set will make
beautiful serial clock

cpu_freq
Function:
Double the speed of the ESP from its normal 80Mhz (80) to 160Mhz (160) or returns
the current value
Use: cpu_freq:integer_value
Example: {cpu_freq:80}
Return: Mqtt none . Serial: OK or string containing speed of chip.
Query: yes
Stored in Flash: yes
Notes: Uses more power at higher speed! Timings generally unaffected. In a test
example of an ESP-01 modified for a larger FLASH (4MBYTE), total power
consumption including 3v3 regulator varied between 30ma and 40ma at 80Meg
rising to 40ma to 50ma at 160Meg.

Home Control 2017 software Page 30


http://tech.scargill.net
dawn
Function:
To pass dawn to the unit number of minutes after midnight
Use: dawn:integer_dawn
Example: {dawn:400}
Return: Mqtt none. Serial: OK
Query: no
Stored in Flash: no

Home Control 2017 software Page 31


http://tech.scargill.net
debug
Function:
To return general information via the serial port
Use: debug
Example: {debug}
Time: 13:56:55 11/08/2016

Time Code: 1470923815

Dusk: 21:08 Dawn: 07:22

On1: 08:00 Off1: 12:00 On2: 15:00 Off2: 23:00 Peak: 23c Off-peak: 19c Frost: 14c

IP: 192:168:1:25

Internal ID: ARPS_00A68508

ID: freddy

DESC: empty

FLAGS:

SSID: wififorus (Active) Pass: xxxxxxxx

SSID2: wififorus Pass2: xxxxxxxx

MQTT Host: 192.168.1.19 Port: 1883 User: admin

OTA Host: www.scargill.net Port: 80

Code Version: 1.5.61

SDK Version: 2.0.0(656edbf)

RSSI: -47

Out0: 0 (0 with invert)

Out4: 0 (1 with invert)

Out5: 0 (0 with invert)

Out12: 0 (0 with invert)

Out15: 0 (0 with invert)

Out16: 0 (0 with invert)

Home Control 2017 software Page 32


http://tech.scargill.net
Sensor Type: DHT22

Temperature Port: GPIO2

GPIO13 available for general use: No

GPIO2 is an input

Sonoff setting=0

WiFi button=2

Invert settings=HEX( 4)

Serial2 settings=0

RGB Indicator=1

Electrodragon=0

No LED clock

CPU frequency: 80Mhz

Free Heap: 16584 bytes

Up Time: 0:25:54

Return: Mqtt none. Serial: debug info


Query: yes
Stored in Flash: no

Home Control 2017 software Page 33


http://tech.scargill.net
desc
Function:
Set or read the optional description of the board
Use: desc
Example: {desk:the kitchen lamp} or {desk?}
Return: Mqtt nothing. Serial: string containing the description if query or OK
Query: yes
Stored in Flash: yes

dusk
Function:
To pass dusk to the unit number of minutes after midnight
Use: dusk:integer_dusk
Example: {dusk:1000}
Return: Mqtt none. Serial: OK
Query: no
Stored in Flash: no

Home Control 2017 software Page 34


http://tech.scargill.net
electrodragon
Function:
if set to true, GPIO16 is used as a status indicator (instead of GPIO13) and not its
normal use
Use: electrodragon:integer_parameter // can be 1 or 0
Example: {electrodragon:1} or {electrodragon:0}
Return: Mqtt electrodragon status. Serial: String containing the status of
electrodragon variable
Query: yes
Stored in Flash: yes
Notes: A quick bodge to allow use of the cheap Electrodragon WIFI boards with 2
relays see the blog.

enable13
Function:
Enable or disable GPIO13 as a general purpose output normally used as a status
indicator
Use: enable13:integer_parameter // can be 1 or 0
Example: {enable13:1} or {enable13:0}
Return: Mqtt none. Serial: OK
Query: no
Stored in Flash: yes
Notes: See rgb_ind

Home Control 2017 software Page 35


http://tech.scargill.net
enable14
Function:
Enable or disable GPIO14 as a general purpose output normally used as an input
Use: enable14:integer_parameter // can be 1 or 0
Example: {enable14:1} or {enable14:0}
Return: Mqtt none. Serial: OK
Query: no
Stored in Flash: yes

enable16
Function:
Allows general use of GPIO16 as an output when wifi_button is 2
Use: enable16:integer_parameter // can be 1 or 0
Example: {enable16:1} or {enable16:0}
Return: Mqtt none. Serial: OK
Query: no
Stored in Flash: no

Home Control 2017 software Page 36


http://tech.scargill.net
ext
Function:
To pass packages onto another unit, say an Arduino or another ESP serially
Use: ext:string_parameter
Example: {ext:hello}
Return: MQTT none. Serial: {string}
Query: no
Stored in Flash: no

flashsize
Function:
Returns manufacturer info on Flash size
Use: flashsize
Example: {flashsize?}
Return: Mqtt Flash size . Serial: string containing flash size
Query: yes
Stored in Flash: no
Notes: Not foolproof as not ALL Flash has the info.

Home Control 2017 software Page 37


http://tech.scargill.net
gettime
Function:
Gets the time from an NTP server
Use: gettime
Example: {gettime?}
Return: Mqtt none . Serial: returns string including time and date from NTP server
Query: yes
Stored in Flash: no
Notes: No daylight saving or local time incorporated but it works. Not used for
anything as boards get time from ESPLOGIN node including time and dusk/dawn etc
(subscribe to logon without the quotes).

gy30_init
Function:
Initialise I2c light sensor
Use: gy30_init
Example: {gy30_init:35}
Return: ok
Query: no
Stored in Flash: no

Home Control 2017 software Page 38


http://tech.scargill.net
gy30_read
Function:
read I2c light sensor
Use: gy30_read
Example: {gy30_read:35}
Return: Mqtt light level . Serial: returns string including light level
Query: yes
Stored in Flash: no

heap
Function:
Return heap size in bytes
Use: heap
Example: {heap?}
Return: Mqtt none. Serial: value
Query: no
Stored in Flash: no

Home Control 2017 software Page 39


http://tech.scargill.net
hitachi
Function:
I2c (gpio4/5) or parallel use of 2 line or 4 line Hitachi-style LCD displays
Use: See section in this manual
Example: {hitachi:39,Hello}
Return: Mqtt none. Serial: OK
Query: no
Stored in Flash: no

hightemperature
Function:
To return temperature value * 10 with more precision than temperature
Use: hightemperature?
Example: {hightemperature?}
Return: Mqtt temperature * 10. Serial: string including temperature
Query: yes
Stored in Flash: no
Notes: See temperature

Home Control 2017 software Page 40


http://tech.scargill.net
hsv
Function:
Controls serial WS2812B RGB serial LEDs using HSV
Use: hsv:integer_port,integer_hue (0-359),integer_saturation (0-255), integer
volume (brightness 0-255), integer_optional_number_of_LEDS (default 10),
integer_optional_delay(default and minimum 2)
Example: {hsv:4,300,255,100,10}
Return: Mqtt none. Serial: OK
Query: no
Stored in Flash: no
Notes: Maximum number of LEDs 300 typically, Delay is in millisecs and is a soft
fade from previous colour to current colour. HSV makes it easier to make a given
colour or shade brighter or darker or to increase or decrease saturation for pastel
colours.

Home Control 2017 software Page 41


http://tech.scargill.net
humidity
Function:
To return humidity value
Use: humidity
Example: {humidity?}
Return: Mqtt humidity. Serial: string including humidity (if using DHT11 or DHT22)
Query: yes
Stored in Flash: no

Home Control 2017 software Page 42


http://tech.scargill.net
i2c
Function:
Read a byte - or write a byte or bytes to i2c
Use: i2c: integer_address // for reading a byte from a device port expander for
example
Use: integer_address , integer_return, integer_value1 --- integer_value5
Example: {i2c:39,0,255} or {i2c:39}
Return: Mqtt value if single argument or arg2==1. Serial: string containing the
value or OK
Query: yes
Stored in Flash: no
Notes: Assuming device PDF8574T with address lines high (7) address is 39. So
{i2c:39,0,1} will set the first output bit high the rest low. Set outputs HIGH before
reading values {i2c:39} will return the byte value of inputs and state of outputs.
Uses GPIO4 and 5. GPIO4 on our boards is SCL, GPIO5 is SDA.
For standard port output
For special cases - my Arduino code set param 1 to 1 to indicate return byte
expected.
So {i2c:8, 0,1,12,1}
Address 8, no return expected, 1 means port output 12 is the port number and 1
is the value
{i2c:8, 1,2,12}
Address, expect return, 2 means port input, port 12 should return the value of port
bit 12

Home Control 2017 software Page 43


http://tech.scargill.net
i2c_check
Function:
Reads a list of connected I2c devices
Use: i2c_check
Example: {i2c_check}
Return: Mqtt nothing. Serial: string containing list of connected I2c devices
Query: yes
Stored in Flash: no

id
Function:
Set or read the name of the board
Use: id
Example: {id:kitchen_lamp} or {id?}
Return: Mqtt nothing. Serial: string containing the ID string if query or OK
Query: yes
Stored in Flash: yes
Notes: You should reboot after setting the ID

Home Control 2017 software Page 44


http://tech.scargill.net
in14
Function:
Reads the state of GPIO14 which is an input
Use: in14
Example: {in14?}
Return: Mqtt value of GPIO14. Serial: string containing value of GPIO145
Query: yes
Stored in Flash: no

in_2bounce
Function:
Integer sets timing for bounce
Use: in_2bounce:integer_value (*25ms)
Example: An mqtt message will be generated when the threshold count is reached
after a level change on gpio2.
Return: Mqtt none . Serial: none
Query: no
Stored in Flash: yes

Home Control 2017 software Page 45


http://tech.scargill.net
in_14bounce
Function:
Integer sets timing for bounce
Use: in_14bounce:integer_value (*25ms)
Example: An mqtt message will be generated when the threshold count is reached
after a level change on gpio14.
Return: Mqtt none . Serial: none
Query: no
Stored in Flash: yes

in14_count
Function:
Reads the number of state changes GPIO14 and kills the count
Use: in14_count
Example: {in14_count?}
Return: Mqtt value of counter. Serial: string containing value of counter
Query: yes
Stored in Flash: no

Home Control 2017 software Page 46


http://tech.scargill.net
in2_count
Function:
Reads the number of state changes GPIO2 and kills the count
Use: in2_count
Example: {in2_count?}
Return: Mqtt value of counter. Serial: string containing value of counter
Query: yes
Stored in Flash: no

invert
Function:
To invert outputs as a group when using OUTx controls ignored by RGB and PWM
commands
Use: invert:integer-mask
Example: {invert 5} inverts OUT0:x and OUT4:x controls

Bit 0 = GPIO0 (1) Bit 5 = GPIO13 (32)

Bit 1 = GPIO2 (2) Bit 6 = GPIO15 (64)

Bit 2 = GPIO4 (4) Bit 7 = GPIO16 (128)


Bit 3 = GPIO5 (8) Bit 8 = GPIO14 (256) (added later
hence compat)
Bit 4 = GPIO12 (16)
Return: Mqtt none. Serial: OK
Query: yes
Stored in Flash: Yes

Home Control 2017 software Page 47


http://tech.scargill.net
invertset
Function:
To invert individual outputs when using OUTx controls ignored by RGB and PWM
commands
Use: invertset:integer-mask
Example: {invertset:4} sets invert status of OUT4

Bit 0 = GPIO0 (1) Bit 5 = GPIO13 (32)

Bit 1 = GPIO2 (2) Bit 6 = GPIO15 (64)

Bit 2 = GPIO4 (4) Bit 7 = GPIO16 (128)


Bit 3 = GPIO5 (8) Bit 8 = GPIO14 (256) (added later
hence compat)
Bit 4 = GPI12 (16)
Return: Mqtt none. Serial: OK
Query: no
Stored in Flash: Yes

Home Control 2017 software Page 48


http://tech.scargill.net
invertreset
Function:
To invert individual outputs when using OUTx controls ignored by RGB and PWM
commands
Use: invert:integer-mask
Example: {invertreset:4} clears invert status of OUT4

Bit 0 = GPIO0 (1) Bit 5= GPIO12 (32)

Bit 1 = GPIO2 (2) Bit 6 = GPIO13 (64)

Bit 2 = GPIO4 (4) Bit 7 = GPIO15 (128)


Bit 3 = GPIO5 (8) Bit 8 = GPIO16 (256) (added later
hence compat)
Bit 4 = GPIO4 (16)
Return: Mqtt none. Serial: OK
Query: no
Stored in Flash: Yes

Home Control 2017 software Page 49


http://tech.scargill.net
kelvin
Function:
Controls serial WS2812B RGB serial LEDs to VERY approximate Kelvin temperature
(i.e. warm and cool)
Use: kelvin:integer_port,integer_temperature (1000-
4000),integer_optional_number_of_LEDS (default 10), integer_optional_delay(default
and minimum 2)
Example: {kelvin:4,5000 ,10}
Return: Mqtt none. Serial: OK
Query: no
Stored in Flash: no
Notes: Maximum number of LEDs 300 typically, KELVIN values very approximate.
Delay is in millisecs and is a soft fade from previous colour temperature to current
colour temperature lower value is warmer. Value of zero will fade the light out
suggest using a longer delay. So for example, to fade out 10 lights on GPIO4,
{kelvin:4,0,10,1000}

led_timer
Function:
To temporarily alter the default 20ms LED timer for RGB/HSV timing etc.
Use: led_timer:integer_value
Example: {led_timer:1000}
Return: Mqtt none. Serial: OK
Query: no
Stored in Flash: no
Notes: minimum value 20 but is 32 bit so you should be able to make for a
ridiculously long timer value

Home Control 2017 software Page 50


http://tech.scargill.net
mist
Function:
Added to control a typical misting system which might be controlled by a relay
Use:
mist:integer_gpio, integer_on_seconds, integer_off_seconds, integer_repeat_count
Example: {mist:0,5,60,100} - i.e. on GPIO, 100 sessions of 5 seconds misting
followed by 60 seconds off do this 100 times
Return: Mqtt none. Serial: OK
Query: no
Stored in Flash: no

mqtt_host
Function:
Set the address of the MQTT broker can be IP or full address
Use: mqtt_host:string_parameter
Example: {mqtt_host:192.168.0.10}
Return: Mqtt nothing. Serial: OK
Query: no
Stored in Flash: yes
Notes: Needs reboot to take effect

Home Control 2017 software Page 51


http://tech.scargill.net
mqtt_pass
Function:
Set the user password of the MQTT broker if needed
Use: mqtt_pass:string_parameter
Example: {mqtt_pass:mypassword}
Return: Mqtt nothing. Serial: OK
Query: no
Stored in Flash: yes
Notes: Needs reboot to take effect

mqtt_port
Function:
Set the port of the MQTT broker usually 1883
Use: mqtt_port:integer_parameter
Example: {mqtt_port:1883}
Return: Mqtt nothing. Serial: OK
Query: no
Stored in Flash: yes
Notes: Needs reboot to take effect

Home Control 2017 software Page 52


http://tech.scargill.net
mqtt_user
Function:
Set the username of the MQTT broker if needed
Use: mqtt_user:string_parameter
Example: {mqtt_user:admin}
Return: Mqtt nothing. Serial: OK
Query: Yes
Stored in Flash: yes
Notes: Needs reboot to take effect

nano
Function:
An early attempt at an Arduino-Nano-based universal i2c peripheral
Use: nano: integer_device, integer_command, integer_value1,integer_value2
Example: {nano:9,1,13,1} or {nano:9,2,12}
Return: Mqtt if 3 parameter query returns value else nothing. Serial: value or OK
Query: Yes but no question mark needed
Stored in Flash: no
Notes: Device can be changed by a command current commands are as follows:
SET_OUTPUT 1
READ_INPUT 2 (no pullups)
READ_INPUT 3 (inputs are set to pullup mode 20k internal pullup resistor)
SET_PWM 4 (values 0-255 only please)
READ_ANALOG 5 (reads 10 bit value back)
SET_ADDRESS 6 (note that address change has no effect until next powerup)

Home Control 2017 software Page 53


http://tech.scargill.net
ota_host
Function:
Set the address of the OTA host can be IP or full address
Use: ota_host:string_parameter
Example: {ota_host:www.fred.net}
Return: Mqtt nothing. Serial: OK
Query: no
Stored in Flash: yes
Notes: Needs reboot to take effect

Home Control 2017 software Page 54


http://tech.scargill.net
ota_port
Function:
Set the address of the OTA port often port 80
Use: ota_port:integer_parameter
Example: {ota_port:80}
Return: Mqtt nothing. Serial: OK
Query: no
Stored in Flash: yes
Notes: Needs reboot to take effect

otaupdate
Function:
To update the code from an OTA server i.e. any old webserver able to return a .bin
file
Use: otaupdate
Example: {otaupdate} causes a reboot on success
Return: Mqtt none. Serial: some status info before the unit reboots
Query: no
Stored in Flash: n/a

Home Control 2017 software Page 55


http://tech.scargill.net
out0
Function:
Output values to GPIO0 or GPIO16 depending on other settings i.e. the relay
channel
Use: out0:integer_value

0 off (if command {invert:1} then state is inverted (for positive-based relays)

1 on (see above)

2 on from dusk till midnight (see above)

3 on from dusk till dawn (see above)

4 on from dawn till dusk (see above)

5 under thermostatic control see relevant command (see above)

6 timer. A second parameter determines ON time in minutes i.e. {out0:6,100}


sets the output on for 100 minutes. If over 10000 in seconds 10000 i.e.
10010=10 secs

-1 toggles the output between off and on. Handy for pushbuttons
7+ under thermostatic control holding at FROST temperature for every increase in
the number, frost status lasts one hour. So value 7 means stay at frost temperature for
2 hours then revert to thermostatic control. *

Example: {out0:1}
Return: Mqtt value of port if query . Serial: string containing value of port if query
or OK
Query: yes
Stored in Flash: yes
Notes: See wifi_button

Home Control 2017 software Page 56


http://tech.scargill.net
out4
Function:
Output values to GPIO4
Use: out4:integer_value

0 off (if command {invert:4} then state is inverted (for positive-based relays)

1 on (see above)

6 timer. A second parameter determines ON time in minutes i.e. {out4:6,100}


sets the output on for 100 minutes. If over 10000 in seconds 10000 i.e.
10010=10 secs

-1 toggles the output between off and on. Handy for pushbuttons

Example: {out4:1}
Return: Mqtt value of port if query . Serial: string containing value of port if query
or OK
Query: yes
Stored in Flash: yes

Home Control 2017 software Page 57


http://tech.scargill.net
out5
Function:
Output values to GPIO5
Use: out5:integer_ value

0 off (if command {invert:8} then state is inverted (for positive-based relays)

1 on (see above)

6 timer. A second parameter determines ON time in minutes i.e. {out5:6,100}


sets the output on for 100 minutes. If over 10000 in seconds 10000 i.e.
10010=10 secs

-1 toggles the output between off and on. Handy for pushbuttons

Example: {out5:1}
Return: Mqtt value of port if query . Serial: string containing value of port if query
or OK
Query: yes
Stored in Flash: yes

Home Control 2017 software Page 58


http://tech.scargill.net
out12
Function:
Output values to GPIO12
Use: out12:integer_value

0 off (if command {invert:16} then state is inverted (for positive-based


relays)

1 on (see above)

6 timer. A second parameter determines ON time in minutes i.e.


{out12:6,100} sets the output on for 100 minutes. If over 10000 in seconds
10000 i.e. 10010=10 secs

-1 toggles the output between off and on. Handy for pushbuttons

Example: {out12:1}
Return: Mqtt value of port if query . Serial: string containing value of port if query
or OK
Query: yes
Stored in Flash: yes

Home Control 2017 software Page 59


http://tech.scargill.net
out13
Function:
Output values to GPIO13
Use: out13:integer_value

0 off (if command {invert:32} then state is inverted (for positive-based


relays)

1 on (see above)

6 timer. A second parameter determines ON time in minutes i.e.


{out13:6,100} sets the output on for 100 minutes. If over 10000 in seconds
10000 i.e. 10010=10 secs

-1 toggles the output between off and on. Handy for pushbuttons
Example: {out13:1}
Return: Mqtt value of port if query . Serial: string containing value of port if query
or OK
Query: yes
Stored in Flash: yes
Notes: Check enabled13 command first generally this port is reserved for status
indicator

Home Control 2017 software Page 60


http://tech.scargill.net
out14
Function:
Output values to GPIO14
Use: out14:integer_value

0 off (if command {invert:64} then state is inverted (for positive-based


relays)

1 on (see above)

6 timer. A second parameter determines ON time in minutes i.e.


{out14:6,100} sets the output on for 100 minutes. If over 10000 in seconds
10000 i.e. 10010=10 secs

-1 toggles the output between off and on. Handy for pushbuttons

Example: {out14:1}
Return: Mqtt value of port if query . Serial: string containing value of port if query
or OK
Query: yes
Stored in Flash: yes
Notes: See enable14 Normally GPiO14 is an input

Home Control 2017 software Page 61


http://tech.scargill.net
out15
Function:
Output values to GPIO15
Use: out15:integer_value

0 off (if command {invert:64} then state is inverted (for positive-based


relays)

1 on (see above)

6 timer. A second parameter determines ON time in minutes i.e.


{out15:6,100} sets the output on for 100 minutes. If over 10000 in seconds
10000 i.e. 10010=10 secs

-1 toggles the output between off and on. Handy for pushbuttons

Example: {out15:1}
Return: Mqtt value of port if query . Serial: string containing value of port if query
or OK
Query: yes
Stored in Flash: yes

Home Control 2017 software Page 62


http://tech.scargill.net
out16
Function:
Output values to GPIO16
Use: out16:integer_value

0 off (if command {invert:128} then state is inverted (for positive-based


relays)

1 on (see above)

6 timer. A second parameter determines ON time in minutes i.e.


{out16:6,100} sets the output on for 100 minutes. If over 10000 in seconds
10000 i.e. 10010=10 secs

-1 toggles the output between off and on. Handy for pushbuttons

Example: {out16:1}
Return: Mqtt value of port if query . Serial: string containing value of port if query
or OK
Query: yes
Stored in Flash: yes
Notes: Check your board does not tie GPIO16 to reset. See wifi_button which must
be set to 0 for GPIO16 to work as an output. If you set wifi_button to 0, you must
reset the board before this will take effect and GPIO16 becomes available.

Home Control 2017 software Page 63


http://tech.scargill.net
xport
Function:
Output values to I2c PCF8574A device 39 (0-7), 38 (8-15) etc for a total of 64
outputs or returns value
Use: xport:integer_value,integer value

0 off (high)

1 on (low)
Or
Xport:integer_value

Example: {xout:1,0} - lights up the second bit of a port 39 extender


Return: ok
Query: yes
Stored in Flash: no.
Notes: Assuming a PCF8574A port expander starting at address 39 and working
down to gpio4 and 5 for I2c. Note outputs are inverted as it is expected that these
open-collector devices will be used with, say, LEDS connected to VCC. Not stored in
FLASH, on power-up the pins are inputs high (off). Do not use with background I2c
operations such as temperature sensors.

Home Control 2017 software Page 64


http://tech.scargill.net
pass
Function:
Set the password string of the network
Use: pass:string_password
Example: {pass:mypassword}
Return: Mqtt nothing. Serial: OK
Query: no
Stored in Flash: yes
Notes: See SSID. Needs reboot to take effect

pass2
Function:
Set the second password string of the network
Use: pass2:string_password
Example: {pass2:myotherpassword}
Return: Mqtt nothing. Serial: OK
Query: no
Stored in Flash: yes
Notes: See SSID2. Needs reboot to take effect

Home Control 2017 software Page 65


http://tech.scargill.net
pca9685
Function:
Controls a PCA9685 board from Adafruit or similar
Use: pca9685: integer chip_number,integer_pin_bit(s),integer_on
Example: {pca9685:64,3,4000}
Return: Mqtt nothing. Serial: OK
Query: no
Stored in Flash: no
Notes: special command pin 0 followed by frequency <1600 is setup. Otherwise
pins ORd together so that 3 means 1 and 2, 0xffff is all

{pca9685:64,0,1600} setup to 1600 and clear all outputs

{pca9685:64,0xffff,20} set all 16 outputs to 20

{pca9685:64,1,20} set first output to 20

{pca9685:64,2,40} set second output to 40

{pca9685:64,4,80} etc

{pca9685:64,8,160}

{pca9685:64,16,320}

{pca9685:64,32,1200}

{pca9685:64,64,2200}

{pca9685:64,128,4096}

Home Control 2017 software Page 66


http://tech.scargill.net
polling_interval
Function:
Polling interval for internal temperature checks
Use: polling_interval:integer_value
Example: {polling_interval:10} (minimum 2 i.e. 2 seconds)
Return: Mqtt value if query. Serial: value if query or OK
Query: no
Stored in Flash: no

port2out
Function:
Set to 1 to make GPIO2 an output
Use: port2out:integer_value
Example: {port2out:1}
Return: Mqtt value if query. Serial: value if query or OK
Query: yes
Stored in Flash: yes

Home Control 2017 software Page 67


http://tech.scargill.net
pwm
Function:
PWM output on GPIO4,5 and 15. On our boards we have optional MOSFETS on these
three for powering the 12v RGB LEDs.
Use: pwm:integer_red (0-99), integer_green (0-99), integer_blue (0,99),
integer_timing(optional min 20)
Example: {pwm:99,40,20 }
Return: Mqtt none. Serial: OK
Query: no
Stored in Flash: no
Notes: The Espressif PWM is done under interrupts and no matter what, once you
start this up it WILL be running in the background. I2C may not work properly and
even RGB LEDs may fail. A better way might be to use a PWM expander board on
I2C as discussed in the blog. Not aware of any other adverse interactions.

pwmhsv
Function:
As for PWM but with HSV values (hue, saturation, brightness)
Use: pwmhsv:integer_hue (0-359), integer_s (0-255), integer_v (0-255),
integer_timing(optional min 20)
Example: {pwmhsv:99,40,20 }
Return: Mqtt none. Serial: OK
Query: no
Stored in Flash: no
Notes: The Espressif PWM is done under interrupts and no matter what, once you
start this up it WILL be running in the background. I2C may not work properly and
even RGB LEDs may fail. A better way might be to use a PWM expander board on

Home Control 2017 software Page 68


http://tech.scargill.net
I2C as discussed in the blog. Not aware of any other adverse interactions.

Home Control 2017 software Page 69


http://tech.scargill.net
rainbow
Function:
Soft-sequences serial WS2812B RGB serial LEDs a mere novelty but it is hypnotic
and BEAUTIFUL
Use: rainbow:integer_port, integer_number_of_LEDS , integer_time_before_fade,
integer_colour_change_speed
Example: {rainbow:4,10,1000,20}
Return: Mqtt none. Serial: OK
Query: no
Stored in Flash: no

rebootnow
Function:
Reboot the board without storing anything in flash
Use: reboot_now
Example: {rebootnow}
Return: Mqtt none. Serial: none
Query: N/A
Stored in Flash: N/A

Home Control 2017 software Page 70


http://tech.scargill.net
reset
Function:
Saves any config and resets the board
Use: reset
Example: {reset}
Return: Mqtt none . Serial: none
Query: no
Stored in Flash: potentially

reset_config
Function:
Wipes config to defaults and resets the board warning you may lose access other
than via serial.
Use: reset_config
Example: {reset_config}
Return: Mqtt none . Serial: none
Query: no
Stored in Flash: yes

Home Control 2017 software Page 71


http://tech.scargill.net
rgb_ind
Function:
If 0, use LED on GPIO13, if 1, use RGB serial LED for colours!!
Use: rgb_ind:integer_value
Example: {rgb_ind:0}
Return: Mqtt none . Serial: OK
Query: no
Stored in Flash: yes
Notes: switching large numbers of LEDs may cause undulation in PWM outputs due
to interrupts not as bad as the normal RGB commands however. With small
numbers, un-noticeable. See enable13.

rgb_lcd
Function:
A series of functions to work with the Grove-LCD RGB Backlight boards which offer
16-char by 2 line Hitachi-style LCD but with RGB backlight. Includes _setup, _clear,
_cursor, _background and _write.
Use: rgb_ind:integer_value
Example:
{rgb_lcd_setup}
{rgb_lcd_background:255,0,0}
{rgb_lcd_cursor:0,0}
{tgb_lcd_write:Hi there}
Return: Mqtt none . Serial: OK
Query: no
Stored in Flash: no

Home Control 2017 software Page 72


http://tech.scargill.net
rgb
Function:
Controls serial WS2812B RGB serial LEDs
Use:
rgb:integer_port,integer_red,integer_green,integer_blue,integer_optional_number_of
_LEDS (default 10), integer_optional_delay (default and minimum 2)
Example: {rgb:4,255,255,255,10}
Return: Mqtt none. Serial: OK
Query: no
Stored in Flash: no
Notes: Maximum number of LEDs 300 typically, RGB values 0-255. Delay is in milli-
secs and is a soft fade from previous colour to current colour. see rgbperm if you
want this state restoring on power-up.

Home Control 2017 software Page 73


http://tech.scargill.net
rgbgo
Function:
fires off serial LED commands as set up by rgbset
Use: rgbgo: integer_port, integer_number_of_LEDs
Example: {rgbgo:4,10}
Return: Mqtt none. Serial: OK
Query: no
Stored in Flash: no
Notes: Should not be used until the rgbset command has filled in values for your
RGB LEDs. In this case 10 serial LEDs on GPIO4 will be programmed.

rgbinstant
Function:
Allow for instant setting of serial RGB lights.
Use: rgbinstant:integer_gpio, integer_red(0-255), integer_green(0-255),
integer_blue(0-255), optional_integer_number (optional default 1)
Example: {rgbinstant:4,255,255,255}
Return: Mqtt none . Serial: OK
Query: no
Stored in Flash: no
Notes: switching large numbers of LEDs may cause undulation in PWM outputs due
to interrupts not as bad as the normal RGB commands however. With small
numbers, un-noticeable

Home Control 2017 software Page 74


http://tech.scargill.net
rgbstop
Function:
Stop the RGB sequencing - see rgbstart and rgbadd
Use: rgbstop
Example: {rgbstop}
Return: Mqtt none. Serial: OK
Query: no
Stored in Flash: no

rgbset
Function:
Fills in an array of values for the rgbgo command
Use: rgbset: integer_start, integer_number, integer_red(0-255), integer_green(0-
255), integer_blue(0-255)
Example: {rgbset:0,10,255,0,0}
Return: Mqtt none. Serial: OK
Query: no
Stored in Flash: no
Notes: In the above example, the buffer will be set so that the first 10 leds (out of
max 300) are set to red. Nothing will happen until the rgbgo command is used.

Home Control 2017 software Page 75


http://tech.scargill.net
rgbstart /add/stop
Function:
RGB animation
For a simple test.
{rgbstop}
{rgbstart:4,4} // port 4, number of LEDS
{rgbadd:1,0,4,255,0,0,500} // command, start LED, number of LEDS, r, g, b, delay
in milliseconds
{rgbadd:1,0,4,0,0,255,500}

Or for a police-car look.


{rgbstop}
{rgbstart:4,8}
{rgbadd:1,0,4,255,0,0,0}
{rgbadd:1,4,4,0,0,255,1000}
{rgbadd:1,0,4,0,0,255,0}
{rgbadd:1,4,4,255,0,255,1000}
The (1) is a command other commands include 2 and 3.
{rgbadd:2,50}
Start a loop which will run 50 times
{rgbadd:3} - End loop. Put stuff in the middle. You can have loops within loops.
You MUST put the {rgbstop} at the beginning as this clears out buffers UNLESS you
are re-using an existing buffer.
The port is set and the timer is started with {rgbstart:port,number_of_leds}
Animation will start with the first rgbadd instruction and run until power-off or an
rgbstop or command 4 (see below).

Home Control 2017 software Page 76


http://tech.scargill.net
The system currently handles up to 300 serial LEDs on any arbitrary GPIO output pin
(only one at a time due to RAM restrictions for the buffers) and the animation buffer
for rgbadd is maximum 600 16-bit characters or 1200 bytes.
For example {rgbadd: 1,0,200,255,255,255,2000} takes in total 10 bytes. You
probably wont run out of animation storage currently set to 600 bytes.
If you use the command 4
{rgbadd:4}
You will stop the existing sequence and return the pointer to the start without
damaging anything so for a sequence you wish to use over and over, simply clear
the LEDs to whatever state you want at the end of the sequence and finish with
command 4.
To start the sequence over at any time use the start command you can even use a
difference output next time if you wish:
If you want to STORE this sequence in FLASH {rgbstore:x} and to get it back
{rgbrecall:x} where x is 0-3 then use {rgbstart:port,number_of_leds} to play it
back. Currently there are 4 non-volatile buffers.

Home Control 2017 software Page 77


http://tech.scargill.net
rgbperm
Function:
Sets RGB lights as in RGB but stores this info. On reboot the lights will resume
the same state unless the gpio was set to -1 - this is handy for those using ESPs as
RGB house lighting. if for any reason the controller (unlikely to be on a UPS) reboots
it will almost instantly resume the same colour on that GPIO pin.
Use: rgbperm:integer_gpio, integer_red(0-255), integer_green(0-255),
integer_blue(0-255), integer_number_of_leds
Example: {rgbinstant:12,255,255,255,10}
Return: Mqtt none . Serial: OK
Query: no
Stored in Flash: yes
Notes: This command is identical to the rgb command other than the permanent
storage of state which survives power cycling. In the event of a power failure, any
serial RGB setting is restored because these LEDs have a tendency on power up to
enter a random state not ideal for household lighting (why couldnt you have
bought ordinary lights like everyone else) with possibly just one LED on it was
felt better to restore the previous state. If you no longer wish to use permanent RGB
set the port to above 16 or -1.

Home Control 2017 software Page 78


http://tech.scargill.net
romswitch
Function:
ASSUMING youve already done an OTA, lets you swap back and forth between the
old version of code and the new
Use:romswitch
Example: {romswitch} causes a reboot on success
Return: Mqtt none. Serial: none
Query: no
Stored in Flash: yes

scan
Function:
Only works in serial scan for WIFI
Use:scan
Example: {scan} lists available SSIDs on success
Return: Mqtt none. Serial: list of SSIDs
Query: no
Stored in Flash: no

Home Control 2017 software Page 79


http://tech.scargill.net
set_serial
Function:
Defines how pins 4 and 5 work
Use: set_serial: integer_value
Example: {set_serial:0}
Parameter:
0 - gpio4 and gpio5 work normally.
1 gpio4 and gpio5 are set to tristate future use
2 - gpio4 and gpio5 become I/O for the Nextion serial display at 57600 baud.
The Nextion itself must have been set to this speed externally using another
source.
3 - gpio4 and gpio5 become I/O for the Nextion serial display at 38400 baud.
The Nextion itself must have been set to this speed externally using another
source.
4 - gpio4 and gpio5 become I/O for the Nextion serial display at 19200 baud.
The Nextion itself must have been set to this speed externally using another
source.
5 - gpio4 and gpio5 become I/O for the Nextion serial display at 9600 baud.
The Nextion itself must have been set to this speed externally using another
source.
Once set, the board will immediately re-boot to set the ports up correctly.
Return: Mqtt none . Serial: OK
Query: yes
Stored in Flash: yes
Notes: Needs reboot to work. See command to_nextion

Home Control 2017 software Page 80


http://tech.scargill.net
si1132_visible, uv and ir
Function:
I2c device SI1132 as found on http://ameridroid.com/products/weather-board-2
Use: si1132_visible , si1132_uv, si1132_ir
Example: {si1132_visible}
Return: Mqtt value . Serial: value
Query: yes
Stored in Flash: no
Notes: Needs reboot if board unplugged then replugged as init done on first use

Home Control 2017 software Page 81


http://tech.scargill.net
sonof
Function:
If set to 1 merely reverses on-off ratio for GPIO13 LED indication. This works for
original Sonoff and the new TH10 and 16. Also if you set the web programming
button to 0, you can toggle the Sonoffs on and off
Use: sonoff:integer_value
Example: {sonoff:0}
Return: Mqtt none . Serial: OK
Query: no
Stored in Flash: yes

ssid
Function:
Set the ssid string of the network
Use:ssid
Example: {ssid:kitchen_wifi}
Return: Mqtt nothing. Serial: OK
Query: no
Stored in Flash: yes
Notes: Needs reboot to take effect

Home Control 2017 software Page 82


http://tech.scargill.net
ssid2
Function:
Set the second ssid string of the network (if the first SSID fails the unit will try the
second SSID etc)
Use:ssid2
Example: {ssid2:ceiling_wifi}
Return: Mqtt nothing. Serial: OK
Query: no
Stored in Flash: yes
Notes: Needs reboot to take effect

swap
Function:
Sets which SSID to try first on next boot (or returns 0 or 1)
Use:swap:integer_parameter 0 or 1
Example: {swap:1}
Return: Mqtt nothing. Serial: string containing 0 or 1 if query or OK
Query: yes
Stored in Flash: yes
Notes: Needs reboot to take effect

Home Control 2017 software Page 83


http://tech.scargill.net
temperature
Function:
To return temperature value
Use: temperature?
Example: {temperature?}
Return: Mqtt temperature. Serial: string including temperature
Query: yes
Stored in Flash: no

temp_type
Function:
To set the type of temperature sensor if any, normally used on GPIO2 can be 14
see below.
Use: temp_type:integer_parameter
Example: {temp_type:1}
Return: MQTT none. Serial: OK
Options:
0 DS18b20
1=DHT22
2=DHT11
3=BME280 on address 0x76
4=BMP280 on address 0x77 with (as appropriate to model) CSB at 3v3 and SDO at
3v3
Query: no
Stored in Flash: yes
See also: temperature port. BME280 uses GPIO4 and 5 for I2C. Depending on the
chip used, see also {temperature?}, {pressure?} and {humidity?}

Home Control 2017 software Page 84


http://tech.scargill.net
temperature_port
Function:
To set the port used for temperature sensing normally 2 but can be 14.
Use: temperature_port:integer_parameter
Example: {temperature_port:2}
Return: MQTT value if query. Serial: value if query else OK
Query: yes
Stored in Flash: yes
Notes: Valid values are 0, 2 or 14. If set to 0 no temperature sensing takes place
and hence no auto-MQTT reporting. If 2 or 14 are set as temperature port- that port
cannot be used for input sensing at the same time.
See also: temp_type

time
Function:
To pass time to the unit in standard long number form number of seconds since
Jan 1970
Use: time:integer_time
Example: {time:34248792}
Return: Mqtt none. Serial: OK
Query: no
Stored in Flash: no

Home Control 2017 software Page 85


http://tech.scargill.net
timeout_set
Function:
A monostable function suitable for watchdog maybe resetting something if no
input in a set time
Use: timeout_set:integer_time_in_seconds,integer_on_time, integer_repeat,
integer_port, integer_invert
Example: {timeout_set:100,10,1,4,0}
In this example times out in 100 seconds stays on for 10 seconds, turns
off and repeats, in this case does NOT invert the output all this on GPIO4
(here)
Return: Mqtt none . Serial: OK
Query: no
Stored in Flash: yes including initial state of pin set timeout to 0 to turn this off
(and reboot)

timeout_clear
Function:
Reset the monostable so something would call this regularly to stop the
monostable triggering
Use: timeout_clear
Example: {timeout_clear}
Return: Mqtt none . Serial: OK
Query: no
Stored in Flash: no
Notes: See timeout_set

Home Control 2017 software Page 86


http://tech.scargill.net
to_nextion
Function:
Send values via software UART to Nextion displays to create a WIFI touch display
Use: to_nextion:string_value
Example: {to_nextion:t0.txt=\Hi there\}
Sends a string to the software serial port suffixed by 0xff 0xff 0xff for the
Nextion displays.
You must use the command to set serial2 to value 2 in order to use this.
If you wish buttons on the Nextion to send commands they must use a tilde
as a separator and use the GET command to ensure the output from the
Nextion ends with FF FF FF.
So for a nextion button. talking to device fred (might be this one might
be another one on the network)
get fred/toesp~{out0:1}
That would turn GPI0 on, on device fred.
The parser handles \r \n \t and \xZZ where zz are 2 hex digits 0-9 or A-F or a-f
Return: Mqtt none . Serial: OK
Query: no
Stored in Flash: no
Notes: See command set_serial

Home Control 2017 software Page 87


http://tech.scargill.net
to_serial2
Function:
Send values via software UART to serial2 (if set) on GPIO4/5 at 56k
Use: to_serial2:string_value
Example: {to_serial2:Hello there \r\n}
Sends a string to the software serial port for general use
You must use the command to set serial2 to value 2 in order to use this.
The parser handles \r \n \t and \xZZ where zz are 2 hex digits 0-9 or A-F or a-f
Return: Mqtt none . Serial: OK
Query: no
Stored in Flash: no
Notes: See set_serial

uptime
Function:
returns a string in h:mm:ss since power up 32 bits so can handle long period. reset
on powerup or system reset.
Use: uptime?
Example: {uptime?}
Return: Mqtt string value . Serial: string value
Query: yes
Stored in Flash: no

Home Control 2017 software Page 88


http://tech.scargill.net
ver
Function:
Returns the current version number
Use: ver
Example: {ver?}
Return: Mqtt version number value. Serial: string containing the version number
Query: yes
Stored in Flash: no

voltage
Function:
Returns the value of the ADC converted to voltage assuming use of our board with
dividers
Use: voltage
Example: {voltage?}
Return: Mqtt voltage value. Serial: string containing the voltage value
Query: yes
Stored in Flash: no

Home Control 2017 software Page 89


http://tech.scargill.net
warning
Function:
Allows a one off light blip on the indicator or colour change on the next OFF period
on the RGB indicator if non-zero
Use: warning integer_r, integer_g,integer_b
Example: {warning:255,0,0}
Return: Mqtt none . Serial: OK
Query: no
Stored in Flash: N/A

web_setup
Function:
Causes the unit to reset into web setup mode as if youd pressed the button
Use: web_setup
Example: {web_setup}
Return: Mqtt none . Serial: none
Query: no
Stored in Flash: N/A

Home Control 2017 software Page 90


http://tech.scargill.net
wifi_button
Function:
Sets which button used for WIFI setup and also determines GPIO0 use generally
use GPIO0
Use: wifi_button: Integer_value
Example: {wifi_button:2}
Return: Mqtt none . Serial: OK
Query: no
Stored in Flash: yes
Notes: If set to 2, GPIO0 is used for general relay operations and output 16 is not
enabled (legacy). If set to 0, GPIO0 is an input and is used for both programming
(ground BEFORE power-up) and as a WIFI button (ground AFTER power-up) and
GPIO16 acts as the general relay output.
When the board is powered up, if the WIFI programming button is held low, you
should see a sequence of + signs on the serial monitor (assuming you have a serial
monitor attached at 115,200 baud).

Home Control 2017 software Page 91


http://tech.scargill.net
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
I.e. if you blow something up - it's your problem. On the other hand if you improve
the code Id like to know about it. Please subscribe to http://tech.scargill.net
If you blow the code and on power-up you see via the serial monitor, +++++ the
board sees the web programming button as being held LOW if this is deliberate
thats fine if not check the WIFI-BUTTON command.

For more information:


http://tech.scargill.net
Twitter:
https://twitter.com/scargill
Facebook:
https://www.facebook.com/esp8266wifi
https://www.facebook.com/iotstuff/
Google+:
https://plus.google.com/+PeterScargill
General:
http://www.scargill.net
http://www.bedrock.es
http://www.hollyberry-cottage.co.uk

Home Control 2017 software Page 92


http://tech.scargill.net