Update for consistency with the other docs
This commit is contained in:
Marcel Stör
parent
8d38cef044
commit
7eba3cbcf3
|
|
@ -5,73 +5,207 @@ The file system is a flat file system, with no notion of directories/folders.
|
|||
|
||||
Only one file can be open at any given time.
|
||||
|
||||
## file.fsinfo()
|
||||
## file.close()
|
||||
|
||||
Return size information for the file system, in bytes.
|
||||
Closes the open file, if any.
|
||||
|
||||
####Syntax
|
||||
`file.fsinfo()`
|
||||
#### Syntax
|
||||
`file.close()`
|
||||
|
||||
####Parameters
|
||||
#### Parameters
|
||||
none
|
||||
|
||||
#### Returns
|
||||
`nil`
|
||||
|
||||
####Returns
|
||||
- `remaining` (number)
|
||||
- `used` (number)
|
||||
- `total` (number)
|
||||
|
||||
####Example
|
||||
|
||||
#### Example
|
||||
```lua
|
||||
-- get file system info
|
||||
remaining, used, total=file.fsinfo()
|
||||
print("\nFile system info:\nTotal : "..total.." Bytes\nUsed : "..used.." Bytes\nRemain: "..remaining.." Bytes\n")
|
||||
```
|
||||
-- open 'init.lua', print the first line.
|
||||
file.open("init.lua", "r")
|
||||
print(file.readline())
|
||||
file.close()
|
||||
```
|
||||
___
|
||||
#### See also
|
||||
[`file.open()`](#fileopen)
|
||||
|
||||
## file.flush()
|
||||
|
||||
Flushes any pending writes to the file system, ensuring no data is lost on a restart. Closing the open file using [`file.close()`](#fileclose) performs an implicit flush as well.
|
||||
|
||||
#### Syntax
|
||||
`file.flush()`
|
||||
|
||||
#### Parameters
|
||||
none
|
||||
|
||||
#### Returns
|
||||
`nil`
|
||||
|
||||
#### Example
|
||||
```lua
|
||||
-- open 'init.lua' in 'a+' mode
|
||||
file.open("init.lua", "a+")
|
||||
-- write 'foo bar' to the end of the file
|
||||
file.write('foo bar')
|
||||
file.flush()
|
||||
-- write 'baz' too
|
||||
file.write('baz')
|
||||
file.close()
|
||||
```
|
||||
#### See also
|
||||
[`file.close()`](#fileclose)
|
||||
|
||||
## file.format()
|
||||
|
||||
Format the file system. Completely erases any existing file system and writes a new one. Depending on the size of the flash chip in the ESP, this may take several seconds.
|
||||
|
||||
####Syntax
|
||||
#### Syntax
|
||||
`file.format()`
|
||||
|
||||
####Parameters
|
||||
#### Parameters
|
||||
none
|
||||
|
||||
#### Returns
|
||||
`nil`
|
||||
|
||||
####Returns
|
||||
`nil`
|
||||
#### See also
|
||||
[`file.remove()`](#fileremove)
|
||||
|
||||
## file.fsinfo()
|
||||
|
||||
Return size information for the file system, in bytes.
|
||||
|
||||
#### Syntax
|
||||
`file.fsinfo()`
|
||||
|
||||
#### Parameters
|
||||
none
|
||||
|
||||
#### Returns
|
||||
- `remaining` (number)
|
||||
- `used` (number)
|
||||
- `total` (number)
|
||||
|
||||
#### Example
|
||||
|
||||
####Example
|
||||
```lua
|
||||
file.format()
|
||||
-- get file system info
|
||||
remaining, used, total=file.fsinfo()
|
||||
print("\nFile system info:\nTotal : "..total.." Bytes\nUsed : "..used.." Bytes\nRemain: "..remaining.." Bytes\n")
|
||||
```
|
||||
|
||||
####See also
|
||||
- `file.remove()`
|
||||
|
||||
___
|
||||
## file.list()
|
||||
|
||||
Lists all files in the file system.
|
||||
|
||||
####Syntax
|
||||
#### Syntax
|
||||
`file.list()`
|
||||
|
||||
####Parameters
|
||||
`nil`
|
||||
#### Parameters
|
||||
none
|
||||
|
||||
####Returns
|
||||
#### Returns
|
||||
a lua table which contains the {file name: file size} pairs
|
||||
|
||||
####Example
|
||||
#### Example
|
||||
```lua
|
||||
l = file.list();
|
||||
for k,v in pairs(l) do
|
||||
print("name:"..k..", size:"..v)
|
||||
end
|
||||
l = file.list();
|
||||
for k,v in pairs(l) do
|
||||
print("name:"..k..", size:"..v)
|
||||
end
|
||||
```
|
||||
___
|
||||
|
||||
## file.open()
|
||||
|
||||
Opens a file for access, potentially creating it (for write modes).
|
||||
|
||||
When done with the file, it must be closed using `file.close()`.
|
||||
|
||||
#### Syntax
|
||||
`file.open(filename, mode)`
|
||||
|
||||
#### Parameters
|
||||
- `filename` file to be opened, directories are not supported
|
||||
- `mode`:
|
||||
- "r": read mode (the default)
|
||||
- "w": write mode
|
||||
- "a": append mode
|
||||
- "r+": update mode, all previous data is preserved
|
||||
- "w+": update mode, all previous data is erased
|
||||
- "a+": append update mode, previous data is preserved, writing is only allowed at the end of file
|
||||
|
||||
#### Returns
|
||||
`nil` if file not opened, or not exists (read modes). `true` if file opened ok.
|
||||
|
||||
#### Example
|
||||
```lua
|
||||
-- open 'init.lua', print the first line.
|
||||
file.open("init.lua", "r")
|
||||
print(file.readline())
|
||||
file.close()
|
||||
```
|
||||
#### See also
|
||||
- [`file.close()`](#fileclose)
|
||||
- [`file.readline()`](#filereadline)
|
||||
|
||||
## file.read()
|
||||
|
||||
Read content from the open file.
|
||||
|
||||
#### Syntax
|
||||
`file.read([n_or_str])`
|
||||
|
||||
#### Parameters
|
||||
- `n_or_str`:
|
||||
- if nothing passed in, read all byte in file
|
||||
- if pass a number n, then read n bytes from file, or EOF is reached
|
||||
- if pass a string "str", then read until 'str' or EOF is reached
|
||||
|
||||
#### Returns
|
||||
fdile content in string, or nil when EOF
|
||||
|
||||
#### Example
|
||||
```lua
|
||||
-- print the first line of 'init.lua'
|
||||
file.open("init.lua", "r")
|
||||
print(file.read('\n'))
|
||||
file.close()
|
||||
|
||||
-- print the first 5 byte of 'init.lua'
|
||||
file.open("init.lua", "r")
|
||||
print(file.read(5))
|
||||
file.close()
|
||||
```
|
||||
|
||||
#### See also
|
||||
- [`file.open()`](#fileopen)
|
||||
- [`file.readline()`](#filereadline)
|
||||
|
||||
## file.readline()
|
||||
|
||||
Read the next line from the open file.
|
||||
|
||||
#### Syntax
|
||||
`file.readline()`
|
||||
|
||||
#### Parameters
|
||||
none
|
||||
|
||||
#### Returns
|
||||
File content in string, line by line, include EOL('\n'). Return `nil` when EOF.
|
||||
|
||||
#### Example
|
||||
```lua
|
||||
-- print the first line of 'init.lua'
|
||||
file.open("init.lua", "r")
|
||||
print(file.readline())
|
||||
file.close()
|
||||
```
|
||||
#### See also
|
||||
- [`file.open()`](#fileopen)
|
||||
- [`file.close()`](#fileclose)
|
||||
- [`file.read()`](#filereade)
|
||||
|
||||
## file.remove()
|
||||
|
||||
Remove a file from the file system. The file must not be currently open.
|
||||
|
|
@ -79,273 +213,119 @@ Remove a file from the file system. The file must not be currently open.
|
|||
###Syntax
|
||||
`file.remove(filename)`
|
||||
|
||||
####Parameters
|
||||
- `filename`: file to remove
|
||||
#### Parameters
|
||||
`filename` file to remove
|
||||
|
||||
####Returns
|
||||
#### Returns
|
||||
`nil`
|
||||
|
||||
####Example
|
||||
#### Example
|
||||
|
||||
```lua
|
||||
-- remove "foo.lua" from file system.
|
||||
file.remove("foo.lua")
|
||||
-- remove "foo.lua" from file system.
|
||||
file.remove("foo.lua")
|
||||
```
|
||||
####See also
|
||||
- `file.open()`
|
||||
___
|
||||
#### See also
|
||||
[`file.open()`](#fileopen)
|
||||
|
||||
## file.rename()
|
||||
|
||||
Renames a file. If a file is currently open, it will be closed first.
|
||||
|
||||
####Syntax
|
||||
#### Syntax
|
||||
`file.rename(oldname, newname)`
|
||||
|
||||
####Parameters
|
||||
- `oldname`: old file name
|
||||
- `newname`: new file name
|
||||
#### Parameters
|
||||
- `oldname` old file name
|
||||
- `newname` new file name
|
||||
|
||||
####Returns
|
||||
#### Returns
|
||||
`true` on success, `false` on error.
|
||||
|
||||
####Example
|
||||
#### Example
|
||||
|
||||
```lua
|
||||
-- rename file 'temp.lua' to 'init.lua'.
|
||||
file.rename("temp.lua","init.lua")
|
||||
-- rename file 'temp.lua' to 'init.lua'.
|
||||
file.rename("temp.lua","init.lua")
|
||||
```
|
||||
___
|
||||
## file.open()
|
||||
|
||||
Opens a file for access, potentially creating it (for write modes).
|
||||
## file.seek()
|
||||
Sets and gets the file position, measured from the beginning of the file, to the position given by offset plus a base specified by the string whence.
|
||||
|
||||
When done with the file, it must be closed using `file.close()`.
|
||||
#### Syntax
|
||||
`file.seek([whence [, offset]])`
|
||||
|
||||
####Syntax
|
||||
`file.open(filename, mode)`
|
||||
#### Parameters
|
||||
- `whence`
|
||||
- "set": base is position 0 (beginning of the file)
|
||||
- "cur": base is current position (default value)
|
||||
- "end": base is end of file
|
||||
- `offset` default 0
|
||||
|
||||
####Parameters
|
||||
- `filename`: file to be opened, directories are not supported
|
||||
- `mode`:
|
||||
- "r": read mode (the default)<br />
|
||||
- "w": write mode<br />
|
||||
- "a": append mode<br />
|
||||
- "r+": update mode, all previous data is preserved<br />
|
||||
- "w+": update mode, all previous data is erased<br />
|
||||
- "a+": append update mode, previous data is preserved, writing is only allowed at the end of file
|
||||
If no parameters are given, the function simply returns the current file offset.
|
||||
|
||||
####Returns
|
||||
- `nil` if file not opened, or not exists (read modes). true` if file opened ok.
|
||||
|
||||
####Example
|
||||
#### Returns
|
||||
the resulting file position, or `nil` on error
|
||||
|
||||
#### Example
|
||||
```lua
|
||||
-- open 'init.lua', print the first line.
|
||||
file.open("init.lua", "r")
|
||||
print(file.readline())
|
||||
file.close()
|
||||
file.open("init.lua", "r")
|
||||
-- skip the first 5 bytes of the file
|
||||
file.seek("set", 5)
|
||||
print(file.readline())
|
||||
file.close()
|
||||
```
|
||||
####See also
|
||||
- `file.close()`
|
||||
- `file.readline()`
|
||||
#### See also
|
||||
[`file.open()`](#fileopen)
|
||||
|
||||
___
|
||||
## file.close()
|
||||
|
||||
Closes the open file, if any.
|
||||
|
||||
####Syntax
|
||||
`file.close()`
|
||||
|
||||
####Parameters
|
||||
`nil`
|
||||
|
||||
####Returns
|
||||
`nil`
|
||||
|
||||
####Example
|
||||
|
||||
```lua
|
||||
-- open 'init.lua', print the first line.
|
||||
file.open("init.lua", "r")
|
||||
print(file.readline())
|
||||
file.close()
|
||||
```
|
||||
####See also
|
||||
- `file.open()`
|
||||
|
||||
___
|
||||
## file.readline()
|
||||
|
||||
Read the next line from the open file.
|
||||
|
||||
####Syntax
|
||||
`file.readline()`
|
||||
|
||||
####Parameters
|
||||
`nil`
|
||||
|
||||
####Returns
|
||||
File content in string, line by line, include EOL('\n'). Return `nil` when EOF.
|
||||
|
||||
####Example
|
||||
|
||||
```lua
|
||||
-- print the first line of 'init.lua'
|
||||
file.open("init.lua", "r")
|
||||
print(file.readline())
|
||||
file.close()
|
||||
```
|
||||
####See also
|
||||
- `file.open()`
|
||||
- `file.close()`
|
||||
- `file.read()`
|
||||
|
||||
___
|
||||
## file.writeline()
|
||||
|
||||
Write a string to the open file and append '\n' at the end.
|
||||
|
||||
####Syntax
|
||||
`file.writeline(string)`
|
||||
|
||||
####Parameters
|
||||
- `string`: content to be write to file
|
||||
|
||||
####Returns
|
||||
`true` if write ok, `nil` on error.
|
||||
|
||||
####Example
|
||||
|
||||
```lua
|
||||
-- open 'init.lua' in 'a+' mode
|
||||
file.open("init.lua", "a+")
|
||||
-- write 'foo bar' to the end of the file
|
||||
file.writeline('foo bar')
|
||||
file.close()
|
||||
```
|
||||
|
||||
####See also
|
||||
- `file.open()`
|
||||
- `file.readline()`
|
||||
|
||||
___
|
||||
## file.read()
|
||||
|
||||
Read content from the open file.
|
||||
####Syntax
|
||||
`file.read([n_or_str])`
|
||||
|
||||
####Parameters
|
||||
- `n_or_str`:
|
||||
- if nothing passed in, read all byte in file.
|
||||
- if pass a number n, then read n bytes from file, or EOF is reached.
|
||||
- if pass a string "str", then read until 'str' or EOF is reached.
|
||||
|
||||
####Returns
|
||||
File content in string, or nil when EOF.
|
||||
|
||||
####Example
|
||||
```lua
|
||||
-- print the first line of 'init.lua'
|
||||
file.open("init.lua", "r")
|
||||
print(file.read('\n'))
|
||||
file.close()
|
||||
|
||||
-- print the first 5 byte of 'init.lua'
|
||||
file.open("init.lua", "r")
|
||||
print(file.read(5))
|
||||
file.close()
|
||||
```
|
||||
|
||||
####See also
|
||||
- `file.open()`
|
||||
- `file.readline()`
|
||||
|
||||
___
|
||||
## file.write()
|
||||
|
||||
Write a string to the open file.
|
||||
|
||||
####Syntax
|
||||
#### Syntax
|
||||
`file.write(string)`
|
||||
|
||||
####Parameters
|
||||
`string`: content to be write to file.
|
||||
#### Parameters
|
||||
`string` content to be write to file
|
||||
|
||||
####Returns
|
||||
`true` if the write is ok, `nil` on error.
|
||||
|
||||
####Example
|
||||
#### Returns
|
||||
`true` if the write is ok, `nil` on error
|
||||
|
||||
#### Example
|
||||
```lua
|
||||
-- open 'init.lua' in 'a+' mode
|
||||
file.open("init.lua", "a+")
|
||||
-- write 'foo bar' to the end of the file
|
||||
file.write('foo bar')
|
||||
file.close()
|
||||
-- open 'init.lua' in 'a+' mode
|
||||
file.open("init.lua", "a+")
|
||||
-- write 'foo bar' to the end of the file
|
||||
file.write('foo bar')
|
||||
file.close()
|
||||
```
|
||||
|
||||
####See also
|
||||
- `file.open()`
|
||||
- `file.writeline()`
|
||||
#### See also
|
||||
- [`file.open()`](#fileopen)
|
||||
- [`file.writeline()`](#filewriteline)
|
||||
|
||||
___
|
||||
## file.flush()
|
||||
## file.writeline()
|
||||
|
||||
Flushes any pending writes to the file system, ensuring no data is lost on a restart. Closing the open file using `file.close()` performs an implicit flush as well.
|
||||
Write a string to the open file and append '\n' at the end.
|
||||
|
||||
####Syntax
|
||||
`file.flush()`
|
||||
#### Syntax
|
||||
`file.writeline(string)`
|
||||
|
||||
####Parameters
|
||||
`nil`
|
||||
#### Parameters
|
||||
`string` content to be write to file
|
||||
|
||||
####Returns
|
||||
`nil`
|
||||
#### Returns
|
||||
`true` if write ok, `nil` on error
|
||||
|
||||
####Example
|
||||
#### Example
|
||||
```lua
|
||||
-- open 'init.lua' in 'a+' mode
|
||||
file.open("init.lua", "a+")
|
||||
-- write 'foo bar' to the end of the file
|
||||
file.write('foo bar')
|
||||
file.flush()
|
||||
-- write 'baz' too
|
||||
file.write('baz')
|
||||
file.close()
|
||||
-- open 'init.lua' in 'a+' mode
|
||||
file.open("init.lua", "a+")
|
||||
-- write 'foo bar' to the end of the file
|
||||
file.writeline('foo bar')
|
||||
file.close()
|
||||
```
|
||||
####See also
|
||||
- `file.close()`
|
||||
|
||||
___
|
||||
## file.seek()
|
||||
Sets and gets the file position, measured from the beginning of the file, to the position given by offset plus a base specified by the string whence.
|
||||
|
||||
####Syntax
|
||||
`file.seek([whence [, offset]])`
|
||||
|
||||
####Parameters
|
||||
- `whence`:
|
||||
- "set": base is position 0 (beginning of the file)
|
||||
- "cur": base is current position (default value)
|
||||
- "end": base is end of file
|
||||
- offset: default 0
|
||||
|
||||
If no parameters are given, the function simply returns the current file offset.
|
||||
|
||||
####Returns
|
||||
The resulting file position, or `nil` on error.
|
||||
|
||||
####Example
|
||||
```lua
|
||||
file.open("init.lua", "r")
|
||||
-- skip the first 5 bytes of the file
|
||||
file.seek("set", 5)
|
||||
print(file.readline())
|
||||
file.close()
|
||||
```
|
||||
####See also
|
||||
- `file.open()`
|
||||
|
||||
___
|
||||
#### See also
|
||||
- [`file.open()`](#fileopen)
|
||||
- [`file.readline()`](#filereadline)
|
||||
|
|
@ -4,232 +4,141 @@ The tmr module allows access to simple timers, the system counter and uptime.
|
|||
|
||||
It is aimed at setting up regularly occurring tasks, timing out operations, and provide low-resolution deltas.
|
||||
|
||||
What the tmr module is *not* however, is a time keeping module. While most timeouts are expressed in milliseconds or even microseconds, the accuracy is limited and compounding errors would lead to rather inaccurate time keeping. Consider using the `rtctime` module for "wall clock" time.
|
||||
What the tmr module is *not* however, is a time keeping module. While most timeouts are expressed in milliseconds or even microseconds, the accuracy is limited and compounding errors would lead to rather inaccurate time keeping. Consider using the [rtctime](rtctime.md) module for "wall clock" time.
|
||||
|
||||
NodeMCU provides 7 timers, numbered 0-6. It is currently up to the user to keep track of which timers are used for what.
|
||||
|
||||
####See also
|
||||
- rtctime module
|
||||
## tmr.alarm()
|
||||
|
||||
This is a convenience function combining [`tmr.register()`](#tmrregister) and [`tmr.start()`](#tmrstart) into a single call.
|
||||
|
||||
To free up the resources with this timer when done using it, call [`tmr.unregister()`](#tmrunregister) on it. For one-shot timers this is not necessary, unless they were stopped before they expired.
|
||||
|
||||
#### Parameters
|
||||
- `id` timer id (0-6)
|
||||
- `interval_ms` timer interval in milliseconds. Maximum value is 12884901. In SDKs <= 1.5.0 values >6871948 result in incorrect behaviour.
|
||||
- `mode` timer mode:
|
||||
- `tmr.ALARM_SINGLE` a one-shot alarm (and no need to call [`tmr.unregister()`](#tmrunregister))
|
||||
- `tmr.ALARM_SEMI` manually repeating alarm (call [`tmr.start()`](#tmrstart) to restart)
|
||||
- `tmr.ALARM_AUTO` automatically repeating alarm
|
||||
|
||||
#### Returns
|
||||
`true` if the timer was started, `false` on error
|
||||
|
||||
#### Example
|
||||
```lua
|
||||
if not tmr.alarm(0, 5000, tmr.ALARM_SINGLE, function() print("hey there") end) then print("whoopsie") end
|
||||
```
|
||||
#### See also
|
||||
- [`tmr.register()`](#tmrregister)
|
||||
- [`tmr.start()`](#tmrstart)
|
||||
- [`tmr.unregister()`](#tmrunregister)
|
||||
|
||||
## tmr.delay()
|
||||
|
||||
Busyloops the processor for a specified number of microseconds.
|
||||
|
||||
This is in general a **bad** idea, because nothing else gets to run, and the networking stack (and other things) can fall over as a result. The only time `tmr.delay()` may be appropriate to use is if dealing with a peripheral device which needs a (very) brief delay between commands, or similar. *Use with caution!*
|
||||
|
||||
Also note that the actual amount of time delayed for may be noticeably greater, both as a result of timing inaccuracies as well as interrupts which may run during this time.
|
||||
|
||||
#### Syntax
|
||||
`tmr.delay(us)`
|
||||
|
||||
#### Parameters
|
||||
`us` microseconds to busyloop for
|
||||
|
||||
#### Returns
|
||||
`nil`
|
||||
|
||||
#### Example
|
||||
```lua
|
||||
tmr.delay(100)
|
||||
```
|
||||
|
||||
## tmr.interval()
|
||||
|
||||
Changes a registered timer's expiry interval.
|
||||
|
||||
#### Syntax
|
||||
`tmr.interval(id, interval_ms)`
|
||||
|
||||
#### Parameters
|
||||
- `id` timer id (0-6)
|
||||
- `interval_ms` new timer interval in milliseconds. Maximum value is 12884901. In SDKs <= 1.5.0 values >6871948 result in incorrect behaviour.
|
||||
|
||||
#### Returns
|
||||
`nil`
|
||||
|
||||
#### Example
|
||||
```lua
|
||||
tmr.register(0, 5000, tmr.ALARM_SINGLE, function() print("hey there") end)
|
||||
tmr.interval(0, 3000) -- actually, 3 seconds is better!
|
||||
```
|
||||
|
||||
## tmr.now()
|
||||
|
||||
Returns the system counter, which counts in microseconds. Limited to 31 bits, after that it wraps around back to zero. That is essential if you use this function to [debounce or throttle GPIO input](https://github.com/hackhitchin/esp8266-co-uk/issues/2).
|
||||
|
||||
#### Syntax
|
||||
`tmr.now()`
|
||||
|
||||
#### Parameters
|
||||
none
|
||||
|
||||
#### Returns
|
||||
the current value of the system counter
|
||||
|
||||
#### Example
|
||||
```lua
|
||||
print(tmr.now())
|
||||
print(tmr.now())
|
||||
```
|
||||
|
||||
## tmr.register()
|
||||
|
||||
Configures a timer and registers the callback function to call on expiry.
|
||||
|
||||
To free up the resources with this timer when done using it, call `tmr.unregister()` on it. For one-shot timers this is not necessary, unless they were stopped before they expired.
|
||||
To free up the resources with this timer when done using it, call [`tmr.unregister()`](#tmrunregister) on it. For one-shot timers this is not necessary, unless they were stopped before they expired.
|
||||
|
||||
####Syntax
|
||||
#### Syntax
|
||||
`tmr.register(id, interval_ms, mode, func)`
|
||||
|
||||
####Parameters
|
||||
- `id`: The timer id (0-6).
|
||||
- `interval_ms`: timer interval in milliseconds. Maximum value is 12884901. In SDKs <= 1.5.0 values >6871948 result in incorrect behaviour.
|
||||
- `mode`: timer mode:
|
||||
- `tmr.ALARM_SINGLE`: a one-shot alarm (and no need to call `tmr.unregister()`)
|
||||
- `tmr.ALARM_SEMI`: manually repeating alarm (call `tmr.start()` to restart)
|
||||
- `tmr.ALARM_AUTO`: automatically repeating alarm
|
||||
#### Parameters
|
||||
- `id` timer id (0-6)
|
||||
- `interval_ms` timer interval in milliseconds. Maximum value is 12884901. In SDKs <= 1.5.0 values >6871948 result in incorrect behaviour.
|
||||
- `mode` timer mode:
|
||||
- `tmr.ALARM_SINGLE` a one-shot alarm (and no need to call [`tmr.unregister()`](#tmrunregister))
|
||||
- `tmr.ALARM_SEMI` manually repeating alarm (call [`tmr.start()`](#tmrunregister) to restart)
|
||||
- `tmr.ALARM_AUTO` automatically repeating alarm
|
||||
|
||||
Note that registering does *not* start the alarm.
|
||||
|
||||
####Returns
|
||||
#### Returns
|
||||
`nil`
|
||||
|
||||
####Example
|
||||
#### Example
|
||||
```lua
|
||||
tmr.register(0, 5000, tmr.ALARM_SINGLE, function() print("hey there") end)
|
||||
tmr.start(0)
|
||||
```
|
||||
####See also
|
||||
- `tmr.alarm()`
|
||||
#### See also
|
||||
[`tmr.alarm()`](#tmralarm)
|
||||
|
||||
___
|
||||
## tmr.unregister()
|
||||
|
||||
Stops the timer (if running) and unregisters the associated callback.
|
||||
|
||||
This isn't necessary for one-shot timers (`tmr.ALARM_SINGLE`), as those automatically unregister themselves when fired.
|
||||
|
||||
####Syntax
|
||||
`tmr.unregister(id)`
|
||||
|
||||
####Parameters
|
||||
- `id`: The timer id (0-6).
|
||||
|
||||
####Returns
|
||||
`nil`
|
||||
|
||||
####Example
|
||||
```lua
|
||||
tmr.unregister(0)
|
||||
```
|
||||
####See also
|
||||
- `tmr.register()`
|
||||
|
||||
___
|
||||
## tmr.start()
|
||||
|
||||
Starts or restarts a previously configured timer.
|
||||
|
||||
####Syntax
|
||||
`tmr.start(id)`
|
||||
|
||||
####Parameters
|
||||
- `id`: The timer id (0-6).
|
||||
|
||||
####Returns
|
||||
True if the timer was started, false on error.
|
||||
|
||||
####Example
|
||||
```lua
|
||||
tmr.register(0, 5000, tmr.ALARM_SINGLE, function() print("hey there") end)
|
||||
if not tmr.start(0) then print("uh oh") end
|
||||
```
|
||||
####See also
|
||||
- `tmr.register()`
|
||||
- `tmr.stop()`
|
||||
- `tmr.unregister()`
|
||||
|
||||
___
|
||||
## tmr.stop()
|
||||
|
||||
Stops a running timer, but does *not* unregister it. A stopped timer can be restarted with `tmr.start()`.
|
||||
|
||||
####Syntax
|
||||
`tmr.stop(id)`
|
||||
|
||||
####Parameters
|
||||
- `id`: The timer id (0-6).
|
||||
|
||||
####Returns
|
||||
True if the timer was stopped, false on error.
|
||||
|
||||
####Example
|
||||
```lua
|
||||
if not tmr.stop(2) then print("timer 2 not stopped, not registered?") end
|
||||
```
|
||||
####See also
|
||||
- `tmr.register()`
|
||||
- `tmr.stop()`
|
||||
- `tmr.unregister()`
|
||||
|
||||
___
|
||||
## tmr.interval()
|
||||
|
||||
Changes a registered timer's expiry interval.
|
||||
|
||||
####Syntax
|
||||
`tmr.interval(id, interval_ms)`
|
||||
|
||||
####Parameters
|
||||
- `id`: The timer id (0-6).
|
||||
- `interval_ms`: new timer interval in milliseconds.
|
||||
|
||||
####Returns
|
||||
`nil`
|
||||
|
||||
####Example
|
||||
```lua
|
||||
tmr.register(0, 5000, tmr.ALARM_SINGLE, function() print("hey there") end)
|
||||
tmr.interval(0, 3000) -- actually, 3 seconds is better!
|
||||
```
|
||||
___
|
||||
## tmr.state()
|
||||
|
||||
Checks the state of a timer.
|
||||
|
||||
####Syntax
|
||||
`tmr.state(id)`
|
||||
|
||||
####Parameters
|
||||
- `id`: The timer id (0-6).
|
||||
|
||||
####Returns
|
||||
(bool, int) or nil
|
||||
|
||||
If the specified timer is registered, returns whether it is currently started and its mode. If the timer is not registered, `nil` is returned.
|
||||
|
||||
####Example
|
||||
```lua
|
||||
running, mode = tmr.state(0)
|
||||
```
|
||||
___
|
||||
## tmr.alarm()
|
||||
|
||||
This is a convenience function combining `tmr.register()` and `tmr.start()` into a single call.
|
||||
|
||||
To free up the resources with this timer when done using it, call `tmr.unregister()` on it. For one-shot timers this is not necessary, unless they were stopped before they expired.
|
||||
|
||||
####Parameters
|
||||
- `id`: The timer id (0-6).
|
||||
- `interval_ms`: timer interval in milliseconds.
|
||||
- `mode`: timer mode:
|
||||
- `tmr.ALARM_SINGLE`: a one-shot alarm (and no need to call `tmr.unregister()`)
|
||||
- `tmr.ALARM_SEMI`: manually repeating alarm (call `tmr.start()` to restart)
|
||||
- `tmr.ALARM_AUTO`: automatically repeating alarm
|
||||
|
||||
####Returns
|
||||
True if the timer was started, false on error.
|
||||
|
||||
####Example
|
||||
```lua
|
||||
if not tmr.alarm(0, 5000, tmr.ALARM_SINGLE, function() print("hey there") end) then print("whoopsie") end
|
||||
```
|
||||
####See also
|
||||
- `tmr.register()`
|
||||
- `tmr.start()`
|
||||
- `tmr.unregister()`
|
||||
|
||||
___
|
||||
## tmr.now()
|
||||
|
||||
Returns the system counter, which counts in microseconds. Limited to 31 bits, after that it wraps around back to zero.
|
||||
|
||||
####Syntax
|
||||
`tmr.now()`
|
||||
|
||||
####Parameters
|
||||
`nil`
|
||||
|
||||
####Returns
|
||||
The current value of the system counter.
|
||||
|
||||
####Example
|
||||
```lua
|
||||
print(tmr.now())
|
||||
print(tmr.now())
|
||||
```
|
||||
___
|
||||
## tmr.time()
|
||||
|
||||
Returns the system uptime, in seconds. Limited to 31 bits, after that it wraps around back to zero.
|
||||
|
||||
####Syntax
|
||||
`tmr.time()`
|
||||
|
||||
####Parameter
|
||||
`nil`
|
||||
|
||||
####Returns
|
||||
The system uptime, in seconds, possibly wrapped around.
|
||||
|
||||
####Example
|
||||
```lua
|
||||
print("Uptime (probably):", tmr.time())
|
||||
```
|
||||
___
|
||||
## tmr.softwd()
|
||||
|
||||
Provides a simple software watchdog, which needs to be re-armed or disabled before it expires, or the system will be restarted.
|
||||
|
||||
####Syntax
|
||||
#### Syntax
|
||||
`tmr.softwd(timeout_s)`
|
||||
|
||||
####Parameters
|
||||
- `timeout_s`: watchdog timeout, in seconds. To disable the watchdog, use -1 (or any other negative value).
|
||||
#### Parameters
|
||||
`timeout_s` watchdog timeout, in seconds. To disable the watchdog, use -1 (or any other negative value).
|
||||
|
||||
####Returns
|
||||
#### Returns
|
||||
`nil`
|
||||
|
||||
####Example
|
||||
#### Example
|
||||
```lua
|
||||
function on_success_callback()
|
||||
tmr.softwd(-1)
|
||||
|
|
@ -240,30 +149,112 @@ tmr.softwd(5)
|
|||
-- go off and attempt to do whatever might need a restart to recover from
|
||||
complex_stuff_which_might_never_call_the_callback(on_success_callback)
|
||||
```
|
||||
___
|
||||
## tmr.delay()
|
||||
|
||||
Busyloops the processor for a specified number of microseconds.
|
||||
## tmr.start()
|
||||
|
||||
This is in general a **bad** idea, because nothing else gets to run, and the
|
||||
networking stack (and other things) can fall over as a result. The only time `tmr.delay()` may be appropriate to use is if dealing with a peripheral device which needs a (very) brief delay between commands, or similar. *Use with caution!*
|
||||
Starts or restarts a previously configured timer.
|
||||
|
||||
Also note that the actual amount of time delayed for may be noticeably greater, both as a result of timing inaccuracies as well as interrupts which may run during this time.
|
||||
#### Syntax
|
||||
`tmr.start(id)`
|
||||
|
||||
####Syntax
|
||||
`tmr.delay(us)`
|
||||
#### Parameters
|
||||
`id` timer id (0-6)
|
||||
|
||||
####Parameters
|
||||
- `us`: microseconds to busyloop for.
|
||||
#### Returns
|
||||
`true` if the timer was started, `false` on error
|
||||
|
||||
####Returns
|
||||
#### Example
|
||||
```lua
|
||||
tmr.register(0, 5000, tmr.ALARM_SINGLE, function() print("hey there") end)
|
||||
if not tmr.start(0) then print("uh oh") end
|
||||
```
|
||||
#### See also
|
||||
- [`tmr.register()`](#tmrregister)
|
||||
- [`tmr.stop()`](#tmrstop)
|
||||
- [`tmr.unregister()`](#tmrunregister)
|
||||
|
||||
## tmr.state()
|
||||
|
||||
Checks the state of a timer.
|
||||
|
||||
#### Syntax
|
||||
`tmr.state(id)`
|
||||
|
||||
#### Parameters
|
||||
`id` timer id (0-6)
|
||||
|
||||
#### Returns
|
||||
(bool, int) or `nil`
|
||||
|
||||
If the specified timer is registered, returns whether it is currently started and its mode. If the timer is not registered, `nil` is returned.
|
||||
|
||||
#### Example
|
||||
```lua
|
||||
running, mode = tmr.state(0)
|
||||
```
|
||||
|
||||
## tmr.stop()
|
||||
|
||||
Stops a running timer, but does *not* unregister it. A stopped timer can be restarted with [`tmr.start()`](#tmrstart).
|
||||
|
||||
#### Syntax
|
||||
`tmr.stop(id)`
|
||||
|
||||
#### Parameters
|
||||
`id` timer id (0-6)
|
||||
|
||||
#### Returns
|
||||
`true` if the timer was stopped, `false` on error
|
||||
|
||||
#### Example
|
||||
```lua
|
||||
if not tmr.stop(2) then print("timer 2 not stopped, not registered?") end
|
||||
```
|
||||
#### See also
|
||||
- [`tmr.register()`](#tmrregister)
|
||||
- [`tmr.stop()`](#tmrstop)
|
||||
- [`tmr.unregister()`](#tmrunregister)
|
||||
|
||||
## tmr.time()
|
||||
|
||||
Returns the system uptime, in seconds. Limited to 31 bits, after that it wraps around back to zero.
|
||||
|
||||
#### Syntax
|
||||
`tmr.time()`
|
||||
|
||||
#### Parameters
|
||||
none
|
||||
|
||||
#### Returns
|
||||
the system uptime, in seconds, possibly wrapped around
|
||||
|
||||
#### Example
|
||||
```lua
|
||||
print("Uptime (probably):", tmr.time())
|
||||
```
|
||||
|
||||
## tmr.unregister()
|
||||
|
||||
Stops the timer (if running) and unregisters the associated callback.
|
||||
|
||||
This isn't necessary for one-shot timers (`tmr.ALARM_SINGLE`), as those automatically unregister themselves when fired.
|
||||
|
||||
#### Syntax
|
||||
`tmr.unregister(id)`
|
||||
|
||||
#### Parameters
|
||||
`id` timer id (0-6)
|
||||
|
||||
#### Returns
|
||||
`nil`
|
||||
|
||||
####Example
|
||||
#### Example
|
||||
```lua
|
||||
tmr.delay(100)
|
||||
tmr.unregister(0)
|
||||
```
|
||||
___
|
||||
#### See also
|
||||
[`tmr.register()`](#tmrregister)
|
||||
|
||||
## tmr.wdclr()
|
||||
|
||||
Feed the system watchdog.
|
||||
|
|
@ -272,17 +263,11 @@ Feed the system watchdog.
|
|||
|
||||
The event-driven model of NodeMCU means that there is no need to be sitting in hard loops waiting for things to occur. Rather, simply use the callbacks to get notified when somethings happens. With this approach, there should never be a need to manually feed the system watchdog.
|
||||
|
||||
####Syntax
|
||||
#### Syntax
|
||||
`tmr.wdclr()`
|
||||
|
||||
####Parameters
|
||||
`nil`
|
||||
#### Parameters
|
||||
none
|
||||
|
||||
####Returns
|
||||
`nil`
|
||||
|
||||
####Example
|
||||
```lua
|
||||
tmr.wdclr()
|
||||
```
|
||||
___
|
||||
#### Returns
|
||||
`nil`
|
||||
|
|
@ -1,73 +1,30 @@
|
|||
# uart Module
|
||||
The uart module allows configuration of and communication over the uart serial port.
|
||||
# UART Module
|
||||
The [UART](https://en.wikipedia.org/wiki/Universal_asynchronous_receiver/transmitter) (Universal asynchronous receiver/transmitter) module allows configuration of and communication over the UART serial port.
|
||||
|
||||
## uart.setup()
|
||||
|
||||
(Re-)configures the communication parameters of the UART.
|
||||
|
||||
####Syntax
|
||||
`uart.setup(id, baud, databits, parity, stopbits, echo)`
|
||||
|
||||
####Parameters
|
||||
- `id`: Always zero, only one uart supported.
|
||||
- `baud`: One of 300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 74880, 115200, 230400, 460800, 921600, 1843200, 2686400.
|
||||
- `databits`: One of 5, 6, 7, 8.
|
||||
- `parity`: uart.PARITY_NONE, uart.PARITY_ODD, or uart.PARITY_EVEN.
|
||||
- `stopbits`: uart.STOPBITS_1, uart.STOPBITS_1_5, or uart.STOPBITS_2.
|
||||
- `echo`: if zero, disable echo, otherwise enable echo.
|
||||
|
||||
####Returns
|
||||
number:configured baud rate
|
||||
|
||||
####Example
|
||||
```lua
|
||||
-- configure for 9600, 8N1, with echo
|
||||
uart.setup(0, 9600, 8, uart.PARITY_NONE, uart.STOPBITS_1, 1)
|
||||
```
|
||||
___
|
||||
## uart.write()
|
||||
|
||||
Write string or byte to the uart.
|
||||
|
||||
####Syntax
|
||||
uart.write(id, data1 [, data2, ...])
|
||||
|
||||
####Parameters
|
||||
- `id`: Always zero, only one uart supported.
|
||||
- `data1`...: String or byte to send via uart.
|
||||
|
||||
####Returns
|
||||
`nil`
|
||||
|
||||
####Example
|
||||
```lua
|
||||
uart.write(0, "Hello, world\n")
|
||||
```
|
||||
___
|
||||
## uart.on()
|
||||
|
||||
Sets the callback function to handle uart events.
|
||||
Sets the callback function to handle UART events.
|
||||
|
||||
Currently only the "data" event is supported.
|
||||
|
||||
####Syntax
|
||||
#### Syntax
|
||||
`uart.on(method, [number/end_char], [function], [run_input])`
|
||||
|
||||
####Parameters
|
||||
- `method`: "data", data has been received on the uart
|
||||
- `number/end_char`:
|
||||
- if pass in a number n<255, the callback will called when n chars are received.
|
||||
- if n=0, will receive every char in buffer.
|
||||
- if pass in a one char string "c", the callback will called when "c" is encounterd, or max n=255 received.
|
||||
- `function`: callback function, event "data" has a callback like this: function(data) end
|
||||
- `run_input`: 0 or 1; If 0, input from uart will not go into Lua interpreter, can accept binary data. If 1, input from uart will go into Lua interpreter, and run.
|
||||
#### Parameters
|
||||
- `method` "data", data has been received on the UART
|
||||
- `number/end_char`
|
||||
- if pass in a number n<255, the callback will called when n chars are received.
|
||||
- if n=0, will receive every char in buffer.
|
||||
- if pass in a one char string "c", the callback will called when "c" is encounterd, or max n=255 received.
|
||||
- `function` callback function, event "data" has a callback like this: `function(data) end`
|
||||
- `run_input` 0 or 1. If 0, input from UART will not go into Lua interpreter, can accept binary data. If 1, input from UART will go into Lua interpreter, and run.
|
||||
|
||||
To unregister the callback, provide only the "data" parameter.
|
||||
|
||||
####Returns
|
||||
#### Returns
|
||||
`nil`
|
||||
|
||||
####Example
|
||||
#### Example
|
||||
```lua
|
||||
-- when 4 chars is received.
|
||||
uart.on("data", 4,
|
||||
|
|
@ -86,5 +43,47 @@ uart.on("data", "\r",
|
|||
end
|
||||
end, 0)
|
||||
```
|
||||
___
|
||||
|
||||
## uart.setup()
|
||||
|
||||
(Re-)configures the communication parameters of the UART.
|
||||
|
||||
#### Syntax
|
||||
`uart.setup(id, baud, databits, parity, stopbits, echo)`
|
||||
|
||||
#### Parameters
|
||||
- `id` always zero, only one uart supported
|
||||
- `baud` one of 300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 74880, 115200, 230400, 460800, 921600, 1843200, 2686400
|
||||
- `databits` one of 5, 6, 7, 8
|
||||
- `parity` `uart.PARITY_NONE`, `uart.PARITY_ODD`, or `uart.PARITY_EVEN`
|
||||
- `stopbits` `uart.STOPBITS_1`, `uart.STOPBITS_1_5`, or `uart.STOPBITS_2`
|
||||
- `echo` if 0, disable echo, otherwise enable echo
|
||||
|
||||
#### Returns
|
||||
configured baud rate (number)
|
||||
|
||||
#### Example
|
||||
```lua
|
||||
-- configure for 9600, 8N1, with echo
|
||||
uart.setup(0, 9600, 8, uart.PARITY_NONE, uart.STOPBITS_1, 1)
|
||||
```
|
||||
|
||||
## uart.write()
|
||||
|
||||
Write string or byte to the UART.
|
||||
|
||||
#### Syntax
|
||||
`uart.write(id, data1 [, data2, ...])`
|
||||
|
||||
#### Parameters
|
||||
- `id` always 0, only one UART supported
|
||||
- `data1`... string or byte to send via UART
|
||||
|
||||
#### Returns
|
||||
`nil`
|
||||
|
||||
#### Example
|
||||
```lua
|
||||
uart.write(0, "Hello, world\n")
|
||||
```
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue