Child pages
  • System
Skip to end of metadata
Go to start of metadata

The system module provides system related functions.

Functions

Function
Description
.getTicks()Returns the number of milliseconds since the device started.
.getTime()

Returns the current local time as a table.

.getUTCTime()

Returns the current UTC time as a table.

.getDateTimeString ( [time,] format )Returns the formatted local date-time string.
.setTime( table )Sets the current local time by providing a table.
.setUTCTime( table )Sets the current UTC time by providing a table.
.setTime( seconds )Sets the current local time by providing Unix Time (seconds since Epoch).
.toEpoch( table )Converts a time table to Unit Time (seconds since Epoch).
.fromEpoch( time )Creates a time table based on the provided Unix Time (seconds since Epoch).
.setMem( address, value [, width] )Sets the value of a memory location.
.getMem( address [, width] )Gets the value of a memory location.
.sleep( milliseconds )Puts the current thread to sleep for a given time in milliseconds.
.cpuUsage()

Returns the current CPU usage.

.reboot( [trigger] )Reboots the system.
.rebootreason()Returns the reason why the device is rebooted.
.memInfo()Returns memory usage information.
.mountSD( owner )Sets the SD-card owner.
.enable5V( state )Enable or disable the 5V output power supply.
.turnOff() Turns off the Screvle.
.getPowerStatus()Returns information about the battery and power status as a table.
.execute( filename )Executes another LUA application.

 Fields

Field nameDescription
firmwareVersionGet the version of the firmware currently running on the device.
firmwareProductGet the product name of the device.
serialNumber

Get the serial number of the device

batchGet the batch nr of the device
hardwareVersionGet the version of the hardware.
productIDGet the product id.
flagsGet extra information about the device.


.getTicks()

Returns the number of milliseconds since the device started. This is a 32-bit value and can overflow.

Return Value
Type
Description
ticksNumberThe number of milliseconds since the device started.

.getTime()

Returns the current (absolute) time as a table. The time is kept by a Real-Time-Clock with battery backup (if fitted).

The returned value is a table with the following fields:

FieldTypeDescription
yearNumberThe current year.
monthNumberThe current month.
dayNumberThe current day of the month.
weekdayStringThe current day of the week.
hoursNumberThe current hour value.
minutesNumberThe current minutes value.
secondsNumberThe current seconds value.

Valid values for weekday are: "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday".

Return Value
Type
Description
timeTableThe current time as a table with above fields.

.getDateTimeString ([time,] format )

Returns the current (absolute) time formatted as a string. The time is kept by a Real-Time-Clock with battery backup (if fitted).

ParameterTypeDescription
formatString

The format of the outputted date string. See the formatting options below. 

characterDescriptionExample

Characters not listed will be copied to the output
YA full numeric representation of a year, 4 digits1999 or 2016
yA two digit representation of a year00 to 99
mNumeric representation of a month, with leading zeros01 to 12
dDay of the month, 2 digits with leading zeros01 to 31
H24-hour format of an hour with leading zeros00 to 24
iMinutes with leading zeros00 to 59
sSeconds, with leading zeros00 to 59
[time]number or table

Optional, the time to format. Can be either:

  • number: Unix time (seconds since epoch)
  • table: Lua table with fields as described in system.getTime()
  • nil: current time is used
Return Value
Type
Description
timeStringThe current time as String.
Example: system.getDateTimeString( format )
print ( system.getDateTimeString ("d-m-Y H:i:s") )
 
-- returns 10-01-2016 14:30:15
 
print( system.getDateTimeString( 1538646741, "d-m-Y H:i:s"  ) )
 
-- returns 04-10-2018 09:52:21

 

 .setTime( table )

Sets the current (absolute) time. The time is kept by a Real-Time-Clock with battery backup (if fitted).

The provided parameter is a table with the following fields:

FieldTypeDescription
yearNumberThe current year.
monthNumberThe current month.
dayNumberThe current day of the month.
hoursNumberThe current hour value.
minutesNumberThe current minutes value.
secondsNumberThe current seconds value.

The correct value of day of the week is calculated.

No return value.


Example: system.setTime( table )
table = {}
table["year"] = 2016
table["month"] = 1
table["day"] = 10
table["hours"] = 14
table["minutes"] = 30
table["seconds"] = 15
system.setTime( table )

.setTime( seconds )

Sets the current (absolute) time. The time is kept by a Real-Time-Clock with battery backup (if fitted).

The provided parameter is a number in Unix time (i.e. indicating the seconds since the Epoch (1 January 1970, midnight UTC) ).

No return value.

.toEpoch( table )

Converts a time table to Unix Time (i.e. indicating the seconds since the Epoch (1 January 1970, midnight UTC) ).

The provided parameter is a table with the following fields:

FieldTypeDescription
yearNumberThe current year.
monthNumberThe current month.
dayNumberThe current day of the month.
hoursNumberThe current hour value.
minutesNumberThe current minutes value.
secondsNumberThe current seconds value.
Return ValueTypeDescription
secondsNumberTime converted to Unix Time.

.fromEpoch( time )

Converts Unix Time (i.e. indicating the seconds since the Epoch (1 January 1970, midnight UTC) ) to a table.

The returned value is a table with the following fields:

FieldTypeDescription
yearNumberThe current year.
monthNumberThe current month.
dayNumberThe current day of the month.
weekdayStringThe current day of the week.
hoursNumberThe current hour value.
minutesNumberThe current minutes value.
secondsNumberThe current seconds value.

Valid values for weekday are: "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday".

Return Value
Type
Description
timeTableThe converted time as a table with above fields.

.setMem( address, value [, width] )

Sets the value of a memory location. This function should be used with caution.

Caution

No memory protection is applied by this function. Incorrect use may damage the device. Only use if you know what you are doing.

Parameter
Type
Description
addressNumberThe memory location to set.
valueNumberThe value to set to the memory location
[width]NumberNumber of bits to write; 8, 16, or 32. Defaults to 32.

No return value.

.getMem( address [, width] )

Gets the value of a memory location. This function should be used with caution.

Caution

No memory protection is applied by this function. Incorrect use may damage the device. Only use if you know what you are doing.

Parameter
Type
Description
addressNumberThe memory location to set.
[width]NumberNumber of bits to write; 8, 16, or 32. Defaults to 32.

Return Value

Type

Description

value

Number

Value of the supplied memory location.

.sleep( milliseconds )

Puts the current thread to sleep for a given time in milliseconds. Other threads continue to run while this thread is sleeping.

ParameterTypeDescription
millisecondsNumberThe number of milliseconds to sleep.

No return value.

.cpuUsage()

Returns the current CPU usage as a number between 0 (0% used) and 1000 (100% used) in 0.1% increments.

This value is updated every 256ms.

Return ValueTypeDescription
usageNumberCPU usage [0,1000] in 0.1% increments.

.reboot( [trigger] )

Reboots the system and optionally triggers the bootloader. If trigger is true, the bootloader will attempt to upgrade the system when rebooting.

ParameterTypeDescription
[trigger]BooleanTrigger upgrade by bootloader. Defaults to false.

This function will never return.

.rebootreason()

Returns string(s) explaining why the device rebooted.

Return ValueTypeDescription
reasonStringReason why the device rebooted.
[details]StringOptional details about the reason.

Possible options are:

ReasonDetailDescription
Reset Unknown
CPU was reset for unknown reasons.
Reset Watchdog
Hardware watchdog reset the CPU.
Reset SoftwareCrashdump CauseSoftware invoked a reset. If the software reset was invoked due to a crashdump being generated, the crashdump cause is detailed in the second return value.
Reset PowerOn
CPU was (re-)powered (Voltage Brownout)
Reset RSTPin
CPU was reset via Reset Pin

.memInfo()

Returns memory usage information.

Return ValueTypeDescription
freeNumberFree memory in bytes.
usedNumberUsed memory in bytes.
blocksNumberUsed memory blocks.
max freeNumberLargest free memory in bytes.

Due to internal overhead, the sum of free and used memory is not always the same.

.mountSD( owner )

Sets the owner of the SD-card. The SD card can be used internally or through a USB mass-storage interface (but not simultaneously). This functions selects which interface mounts (owns) the SD card.

ParameterTypeDescription
ownerStringValid values are "local" (default) or "USB".

You should always close all files before changing the SD-card owner to avoid corrupting the filesystem.

.enable5V( state )

Enable or disable the 5V output power supply.

ParameterTypeDescription
stateBoolean

True -> Enable 5V.

False -> Disable 5V.

No return value.

.turnOff()

Calling this function will shutdown the Screvle device.

No return value.

.getPowerStatus()

Returns information about the battery and power status as a table.

The returned value is a table with the following fields:

FieldTypeDescription
statusString

Returns the power status: "battery", "charging", "charged", "fault".


levelNumberVoltage level of the battery in mV.
poweredBoolean

True -> external power is connected.

False -> Screvle is battery powered.

faultBoolean

True -> error occurred while charging the battery (e.g. when charging is paused due to overheating).

False -> no faults detected.

chargingBoolean

True -> the battery is being charged.

False -> the battery is fully charged or the battery isn't connected.

.execute()

Executes another Lua file. This resets the whole Lua environment, so all existing Lua variables and functions are no longer available when the new application starts. This is compareable to running an application via the webide with "Reset Lua Environment" enabled.

This function will fail if the main Lua thread is still running. The main Lua thread is the one that parses and runs the file that is executed. Typically the main Lua thread initializes the system and then returns (silently) at the end of the Lua file that is executed. system.execute is usually called from a UI actionHandler.

FieldTypeDescription
filenameString

Filename of the Lua file to execute. E.g. "LUA/MENU.LUA"

Filename must include the "LUA/" directory name.

firmwareVersion

Get the version of the firmware currently running on the device.

example: 2.1.3

firmwareProduct

Get the product name of the device.

example: screvle

serialNumber

Get the serial number of the device

example: MINI-B-00000012

batch

Get the batch nr of the device. This is an encoded value that contains the year and month of production, followed by the product nr of that month. The value is encoded in little endian, in the following order:

production batch (2 bytes) - month (1 byte) - year (1 byte).

example: 0x01000616
this means: production batch 0001, in month 6 of year 16

hardwareVersion

Get the version of the hardware. This is a 2 bytes integer containing the revision nr in the least significant byte and the variant in the most significant byte.

example: 514 (0x202)
decoded: 2 + (256 * 2) -> most significant byte = 2, least significant byte = 2 -> R2 variant B

processorVariantValue
L486A1
F4B2
L496D4


productID

Get the product id.

Possible values:

valuemeaning
1

screvle handheld

10screvle mini


flags

Get extra information about the device.

Available flags: (values are combined with 'or')

valuemeaning
0x0001wifi equiped
0x0002no battery charger



Screvle can't detect the difference between a fully charged battery and a battery that isn't connected. Therefore the status will return "charged" even when the Screvles is powered using an external power source and the battery isn't connected.



  • No labels