-
Notifications
You must be signed in to change notification settings - Fork 6
1.2 Command Reference
ddtlabs edited this page Jan 13, 2017
·
10 revisions
#Command Reference#
- You have to define a bridge device before any logical device can be defined.
- You have to configure your ESP to use "FHEM HTTP" controller protocol. Furthermore the ESP controller port and the FHEM ESPEasy bridge port must be the same, of cause.
- ESPEasy build >= R128 (self compiled) or an ESPEasy precompiled image >=
R140_RC3
- perl module JSON
Use "cpan install JSON" or operating system's package manager to install Perl JSON Modul. Depending on your os the required package is named: libjson-perl or perl-JSON.
Provides access and control to ESP8266/ESPEasy
Notes:
Requirements:
Define (bridge)
define <name> ESPEasy bridge <port><li>
<code><name></code><br>
Specifies a device name of your choise.<br>
eg. <code>ESPBridge</code></li><br>
<li>
<code><port></code><br>
Specifies tcp port for incoming http requests. This port must <u>not</u>
be used by any other application or daemon on your system and must be in
the range 1025..65535<br>
eg. <code>8383</code> (ESPEasy FHEM HTTP plugin default)</li><br>
<li>
Example:<br>
<code>define ESPBridge ESPEasy bridge 8383</code></li><br>
Get (bridge)
- <reading>
returns the value of the specified reading
<li><b>user</b><br>
returns username used by basic authentication for incoming requests.
</li><br>
<li><b>pass</b><br>
returns password used by basic authentication for incoming requests.
</li><br>
Set (bridge)
-
help
Shows set command usage
required values:help|pass|user
<li><b>pass</b><br>
Specifies password used by basic authentication for incoming requests.<br>
required value: <code><password></code><br>
eg. : <code>set ESPBridge pass secretpass</code></li><br>
<li><b>user</b><br>
Specifies username used by basic authentication for incoming requests.<br>
required value: <code><username></code><br>
eg. : <code>set ESPBridge user itsme</code></li><br>
Attributes (bridge)
-
allowedIPs
Used to limit IPs or IP ranges of ESPs which are allowed to commit data.
Specify comma separated list of IPs or IP ranges. Netmask can be written as bitmask or dotted decimal. Domain names for dns lookups are not supported.
Possible values: IPv64 address, IPv64/netmask
Default: 0.0.0.0/0 (all IPs are allowed)
Eg. 10.68.30.147
Eg. 10.68.30.0/24,10.68.31.0/255.255.248.0
Eg. fe80::/10,2001:1a59:50a9::/48,2002:1a59:50a9::,2003:1a59:50a9:acdc::36
<li><b>authentication</b><br>
Used to enable basic authentication for incoming requests<br>
Note that user, pass and authentication attribute must be set to activate
basic authentication<br>
Possible values: 0,1<br>
Default: 0</li><br>
<li><b>autocreate</b><br>
Used to overwrite global autocreate setting<br>
Possible values: 0,1<br>
Default: not set</li><br>
<li><b>autosave</b><br>
Used to overwrite global autosave setting<br>
Possible values: 0,1<br>
Default: not set</li><br>
<li><b>combineDevices</b><br>
Used to gather all ESP devices of a single ESP into 1 FHEM device even if
different ESP devices names are used.<br>
Possible values: 0, 1, IPv64 address, IPv64/netmask, ESPname or a comma
separated list consisting of these values.<br>
Netmasks can be written as bitmask or dotted decimal. Domain names for dns
lookups are not supported.<br>
Default: 0 (disabled for all ESPs)<br>
Eg. 1 (globally enabled)<br>
Eg. ESP01,ESP02<br>
Eg. 10.68.30.1,10.69.0.0/16,ESP01,2002:1a59:50a9::/48</li><br>
<li><b>deniedIPs</b><br>
Used to define IPs or IP ranges of ESPs which are denied to commit data.
<br>
Syntax see <b>allowedIPs</b>.<br>
This attribute will overwrite any IP or range defined by
<b>allowedIPs</b>.<br>
Default: none (no IPs are denied)</li><br>
<li><b>disable</b><br>
Used to disable device<br>
Possible values: 0,1<br>
Default: 0 (eanble)</li><br>
<li><b>httpReqTimeout</b><br>
Specifies seconds to wait for a http answer from ESP8266 device<br>
Possible values: 4..60<br>
Default: 10 seconds</li><br>
<li><b>uniqIDs</b><br>
This attribute has been removed.</li><br>
Define (logical device)
-
Notes: Logical devices will be created automatically if any values are
received by the bridge device and autocreate is not disabled. If you
configured your ESP in a way that no data is send independently then you
have to define logical devices. At least wifi rssi value could be defined
to use autocreate.
<code>define <name> ESPEasy <ip|fqdn> <port>
<IODev> <identifier></code><br><br>
<li>
<code><name></code><br>
Specifies a device name of your choise.<br>
eg. <code>ESPxx</code></li><br>
<li>
<code><ip|fqdn></code><br>
Specifies ESP IP address or hostname.<br>
eg. <code>172.16.4.100</code><br>
eg. <code>espxx.your.domain.net</code></li><br>
<li>
<code><port></code><br>
Specifies http port to be used for outgoing request to your ESP. Should
be: 80<br>
eg. <code>80</code></li><br>
<li>
<code><IODev></code><br>
Specifies your ESP bridge device. See above.<br>
eg. <code>ESPBridge</code></li><br>
<li>
<code><identifier></code><br>
Specifies an identifier that will bind your ESP to this device.<br>
This identifier must be specified in this form:
<esp name>_<esp device name>.<br> If attribute
<b>combineDevices</b> is used then
<esp name> is used, only.<br>
ESP name and device name can be found here:<br>
<esp name>: => ESP GUI => Config => Main Settings =>
Name<br>
<esp device name>: => ESP GUI => Devices => Edit =>
Task Settings => Name<br>
eg. <code>ESPxx_DHT22</code><br>
eg. <code>ESPxx</code></li><br>
<li> Example:<br>
<code>define ESPxx ESPEasy 172.16.4.100 80 ESPBridge EspXX_SensorXX</code>
</li><br>
Get (logical device)
- <reading>
returns the value of the specified reading
<li><b>pinMap</b><br>
returns possible alternative pin names that can be used in commands</li>
<br>
Set (logical device)
-
Notes:
- Commands are case insensitive.
- Users of Wemos D1 mini or NodeMCU can use Arduino pin names instead of GPIO numbers:
D1 => GPIO5, D2 => GPIO4, ...,TX => GPIO1 (see: get pinMap)
- low/high state can be written as 0/1 or on/off
<li><b>clearReadings</b><br>
Delete all readings that are auto created by received sensor values
since last FHEM restart.<br>
required values: <code><none></code></li><br>
<li><b>help</b><br>
Shows set command usage.<br>
required values: <code>a valid set command</code></li><br>
<li><b>raw</b><br>
Can be used for own ESP plugins or new ESPEasy commands that are not
considered by this module at the moment. Any argument will be sent
directly to the ESP.<br>
Usage: raw <cmd> <param1> <param2> <...><br>
eg: raw myCommand 3 1 2</li><br>
<li><b>rgb</b><br>
EXPERIMENTAL, may be removed in later version if a rgb plugin is
available.<br>
Used to control a rgb light.<br>
You have to set attribute 'rgbGPIOs' to enable this feature. Default
colorpicker mode is HSVp but can be adjusted with help of attribute
'colorpicker' to HSV or RGB. Use attribute 'webCmd rgb' to display a
colorpicker in FHEMWEB room view or on detail page.<br>
required argument: <code><rrggbb>|on|off|toggle</code>
<br>
eg. rgb 00FF00<br>
eg. rgb on<br>
eg. rgb off<br>
eg. rgb toggle<br>
<br>
<u>Full featured example:</u><br>
attr <ESP> colorpicker HSVp<br>
attr <ESP> devStateIcon { ESPEasy_devStateIcon($name) }<br>
attr <ESP> Interval 30<br>
attr <ESP> parseCmdResponse status,pwm<br>
attr <ESP> pollGPIOs D6,D7,D8<br>
attr <ESP> rgbGPIOs D6,D7,D8<br>
attr <ESP> webCmd rgb:rgb ff0000:rgb 00ff00:rgb 0000ff:toggle:on :off
<br>
</li><br>
<li><b>statusRequest</b><br>
Trigger a statusRequest for configured GPIOs (see attribut pollGPIOs)
and do a presence check<br>
required values: <code><none></code></li><br>
<br>
<b>Note:</b> The following commands are built-in ESPEasy Software commands
that are send directly to the ESP after passing a syntax check. A detailed
description can be found here:
<a href="http://www.letscontrolit.com/wiki/index.php/ESPEasy_Command_Reference" target="_NEW">ESPEasy Command Reference</a><br><br>
<li><b>Event</b><br>
Create an event. Such events can be used in ESP rules.<br>
required value: <code><string></code></li><br>
<li><b>GPIO</b><br>
Direct control of output pins (on/off)<br>
required arguments: <code><pin> <0,1></code><br>
</li><br>
<li><b>PWM</b><br>
Direct PWM control of output pins<br>
required arguments: <code><pin> <level></code><br>
</li><br>
<li><b>PWMFADE</b><br>
PWMFADE control of output pins<br>
required arguments: <code><pin> <target> <duration>
</code><br>
pin: 0-3 (0=r,1=g,2=b,3=w), target: 0-1023, duration: 1-30 seconds.
</li><br>
<li><b>Lights</b> (plugin can be found <a
href="https://github.com/ddtlabs/ESPEasy-Plugin-Lights">here</a>)<br>
Control a rgb or ct light<br>
required arguments: <code><cmd> <color> <fading time>
</code><br>
cmd: rgb, ct, pct, on, off, toggle<br>
color: rrggbb (if rgb) or color temperature in Kelvin (if ct)<br>
fading time: time in seconds<br>
eg. <code>set <esp> rgb aa00aa</code><br>
eg. <code>set <esp> ct 3200</code><br>
eg. <code>set <esp> pct 50</code><br>
eg. <code>set <esp> on</code><br>
eg. <code>set <esp> off</code><br>
eg. <code>set <esp> toggle</code><br>
</li><br>
<li><b>Pulse</b><br>
Direct pulse control of output pins<br>
required arguments: <code><pin> <0,1> <duration></code>
<br>
</li><br>
<li><b>LongPulse</b><br>
Direct pulse control of output pins<br>
required arguments: <code><pin> <0,1> <duration></code>
<br>
</li><br>
<li><b>Servo</b><br>
Direct control of servo motors<br>
required arguments: <code><servoNo> <pin> <position>
</code><br>
</li><br>
<li><b>lcd</b><br>
Write text messages to LCD screen<br>
required arguments: <code><row> <col> <text></code><br>
</li><br>
<li><b>lcdcmd</b><br>
Control LCD screen<br>
required arguments: <code><on|off|clear></code><br>
</li><br>
<li><b>mcpgpio</b><br>
Control MCP23017 output pins<br>
required arguments: <code><pin> <0,1></code><br>
</li><br>
<li><b>oled</b><br>
Write text messages to OLED screen<br>
required arguments: <code><row> <col> <text></code><br>
</li><br>
<li><b>oledcmd</b><br>
Control OLED screen<br>
required arguments: <code><on|off|clear></code><br>
</li><br>
<li><b>pcapwm</b><br>
Control PCA9685 pwm pins<br>
required arguments: <code><pin> <level></code><br>
</li><br>
<li><b>PCFLongPulse</b><br>
Long pulse control on PCF8574 output pins<br>
</li><br>
<li><b>PCFPulse</b><br>
Pulse control on PCF8574 output pins<br>
</li><br>
<li><b>pcfgpio</b><br>
Control PCF8574 output pins<br>
</li><br>
<li><b>irsend</b><br>
Send ir codes via "Infrared Transmit" Plugin<br>
Supported protocols are: NEC, JVC, RC5, RC6, SAMSUNG, SONY, PANASONIC at
the moment. As long as official documentation is missing you can find
some details here:
<a href="http://www.letscontrolit.com/forum/viewtopic.php?f=5&t=328">
IR Transmitter thread</a><br>
required arguments: <code><protocol> <hex code> <bit length
of hex code>
</code><br>
eg. <code>irsend NEC 7E81542B 32</code>
</li><br>
<li><b>status</b><br>
Request esp device status (eg. gpio)<br>
required values: <code><device> <pin></code><br>
eg: <code>gpio 13</code></li><br>
<b>Administrative commands</b> (be careful):<br><br>
<li><b>reboot</b><br>
Used to reboot your ESP<br>
required values: <code>none</code><br>
</li><br>
<li><b>reset</b><br>
Do a factory reset on the ESP<br>
required values: <code>none</code><br>
</li><br>
<li><b>erase</b><br>
Wipe out ESP flash memory<br>
required values: <code>none</code><br>
</li><br>
Attributes (logical device)
-
adjustValue
Used to adjust sensor values
Must be a space separated list of <reading>:<formula>. Reading can be a regexp. Formula can be an arithmetic expression like 'round(($VALUE-32)*5/9,2)'. If $VALUE is omitted in formula then it will be added to the beginning of the formula. So you can simple write 'temp:+20' or '.*:*4'
Modified or ignored values are marked in the system log (verbose 4). Use verbose 5 logging to see more details.
If the used sub function returns 'undef' then the value will be ignored.
The following variables can be used if necessary:- $VALUE contains the original value
- $READING contains the reading name
- $NAME contains the device name
Eg.attr ESPxx adjustValue humidity:+0.1 temperature+*:($VALUE-32)*5/9
Eg.attr ESPxx adjustValue .*:my_OwnFunction($NAME,$READING,$VALUE)
Sample function to ignore negative values:
sub my_OwnFunction($$$) {
my ($name,$reading,$value) = @_;
return ($value < 0) ? undef : $value;
}
<li><b>colorpicker</b><br>
Used to select colorpicker mode<br>
Possible values: RGB,HSV,HSVp<br>
Default: HSVp</li><br>
<li><b>colorpickerCTcw</b><br>
Used to select ct colorpicker's cold white color temperature in Kelvin<br>
Possible values: > colorpickerCTww<br>
Default: 6000</li><br>
<li><b>colorpickerCTww</b><br>
Used to select ct colorpicker's warm white color temperature in Kelvin<br>
Possible values: < colorpickerCTcw<br>
Default: 2000</li><br>
<li><b>disable</b><br>
Used to disable device<br>
Possible values: 0,1<br>
Default: 0</li><br>
<li><b>Interval</b><br>
Used to set polling interval for presence check and GPIOs polling in
seconds. 0 will disable this feature.<br>
Possible values: secs > 10.<br>
Default: 300</li><br>
<li><b>presenceCheck</b><br>
Used to enable/disable presence check for ESPs<br>
Presence check determines the presence of a device by readings age. If any
reading of a device is newer than <b>interval</b>
seconds than it is marked as being present. This kind of check works for
ESP devices in deep sleep too but require at least 1 reading that is
updated regularly.<br>
Possible values: 0,1<br>
Default: 1 (enabled)</li><br>
<li><b>readingSwitchText</b><br>
Use on,off instead of 1,0 for readings if ESP device is a switch.<br>
Possible values: 0,1<br>
Default: 1 (enabled)</li><br>
<li><b>rgbGPIOs</b><br>
Use to define GPIOs your lamp is conneted to.<br>
Possible values: Comma separated tripple of ESP pin numbers or arduino pin
names<br>
Eg: 12,13,15<br>
Eg: D6,D7,D8<br>
Default: none</li><br>
<li><b>setState</b><br>
Summarize received values in state reading.<br>
A positive number determines the number of characters used for reading
names. Only readings with an age less than
interval will be considered.<br>
If your are not satisfied with format or behavior of setState then
disable this attribute (set to 0) and use global attributes userReadings
and/or stateFormat to get what you want.<br>
Possible values: integer >=0<br>
Default: 3 (enabled with 3 characters abbreviation)</li><br>
The following two attributes should only be use in cases where ESPEasy
software do not send data on status changes and no rule/dummy can be used
to do that. Useful for commands like PWM, STATUS, ...
<br><br>
<li><b>parseCmdResponse</b><br>
Used to parse response of commands like GPIO, PWM, STATUS, ...<br>
Specify a module command or comma separated list of commands as argument.
Commands are case insensitive.<br>
Only necessary if ESPEasy software plugins do not send their data
independently. Useful for commands line STATUS, PWM, ...<br>
Possible values: <set cmd>[,<set cmd>][,...]<br>
Default: status<br>
Eg. <code>attr ESPxx parseCmdResponse status,pwm</code></li><br>
<li><b>pollGPIOs</b><br>
Used to enable polling for GPIOs status. This polling will do same as
command 'set ESPxx status <device> <pin>'<br>
Possible values: GPIO number or comma separated GPIO number list<br>
Default: none<br>
Eg. <code>attr ESPxx pollGPIOs 13,D7,D2</code></li><br>
The following two attributes control naming of readings that are
generated by help of parseCmdResponse and pollGPIOs (see above)
<br><br>
<li><b>readingPrefixGPIO</b><br>
Specifies a prefix for readings based on GPIO numbers. For example:
"set ESPxx pwm 13 512" will switch GPIO13 into pwm mode and set pwm to
512. If attribute readingPrefixGPIO is set to PIN and attribut
parseCmdResponse contains pwm command then the reading name
will be PIN13.<br>
Possible Values: <code>string</code><br>
Default: GPIO</li><br>
<li><b>readingSuffixGPIOState</b><br>
Specifies a suffix for the state-reading of GPIOs (see Attribute
<b>pollGPIOs</b>)<br>
Possible Values: <code>string</code><br>
Default: no suffix<br>
Eg. attr ESPxx readingSuffixGPIOState _state</li><br>