# sys module

| Status | Last Update | API Version |
| ------ | ------ | ------ |
| Active | 2019-11-14 | V1.00.00 |

## Version format
Let's first define a version format.
Let's call this format the `naïve` format, defined as the following:
A uint32 is the version, where the higher number means the newer.
When converted to human-readable string, two comma is inserted into the last second and the last fourth digits. For example, 12345 (DEC) is converted into V1.23.45, and V1.23.45 is newer than V1.23.44

## sys.gHWVer()
### Description
Get the hardware version in `naïve` format.
### Parameters
nil
### Return value

| Name | Type | Range | Usage |
| ------ | ------ | ------ |  ------ |
| HW_VER | number|  | Hardware version |

### Example call
```lua
hwVer = sys.gHWVer()
```

## sys.gFWVer()
### Description
Get the firmware version in `naïve` format.
### Parameters
nil
### Return value

| Name | Type | Range | Usage |
| ------ | ------ | ------ |  ------ |
| FW_VER | number|  | Firmware version |

### Example call
```lua
fwVer = sys.gFaWVer()
```

## sys.gIsUSBPowered()
### Description
Check if USB 5V power source is connected
### Parameters
nil
### Return value

| Name | Type | Range | Usage |
| ------ | ------ | ------ |  ------ |
| connected | boolean|  | is connected |

### Example call
```lua
isConnected = sys.gIsUSBPowered()
```

## sys.gTick()
### Description
Get system tick of the RTOS.
### Parameters
nil
### Return value

| Name | Type | Range | Usage |
| ------ | ------ | ------ |  ------ |
| tick | number|  | Tick count since startup(Tick frequency is 1000HZ) |

### Example call
```lua
tick = sys.gTick()
```

## sys.sLuaModDebug()
### Description
Set if lua API debug is enabled.
This enable/disables the debug prints from lua API. It's for debug purpose of the API themselves. Debug message is printed to the terminal.
### Parameters

| Name | Type | Range | Usage |
| ------ | ------ | ------ |  ------ |
| status | number|  | 1 means enable, 0 means disable, the default value is 0 |

### Return value
nil
### Example call
```lua
sys.sLuaModDebug(1)
```

## sys.gLuaAPIVer()
### Description
Get the lua API version in `naïve` format.
### Parameters
nil
### Return value

| Name | Type | Range | Usage |
| ------ | ------ | ------ |  ------ |
| API_VER | number|  | API version |

### Example call
```lua
apiVer = sys.gLuaAPIVer()
```
## sys.gTotalHeap()
### Description
Get total heap size of the system.
### Parameters
nil
### Return value

| Name | Type | Range | Usage |
| ------ | ------ | ------ |  ------ |
| size | number|  | Heap size in bytes |

### Example call
```lua
heapTotal = sys.gTotalHeap()
```

## sys.gFreeHeap()
### Description
Get size of the free heap in the system.
### Parameters
nil
### Return value

| Name | Type | Range | Usage |
| ------ | ------ | ------ |  ------ |
| size | number|  | Free heap size in bytes |

### Example call
```lua
heapFree = sys.gFreeHeap()
```

## sys.gFreeHeapEver()
### Description
Get the size of the minimum free heap since start-up, this is used to evaluate the peak memory usage.
### Parameters
nil
### Return value

| Name | Type | Range | Usage |
| ------ | ------ | ------ |  ------ |
| size | number|  | Minimum free heap size in bytes |

### Example call
```lua
heapFreeEver = sys.gFreeHeapEver()
```

## sys.gVDD()
### Description
Get the voltage of power rail VDD in the system. This value is 3.3V typically.
### Parameters
nil
### Return value

| Name | Type | Range | Usage |
| ------ | ------ | ------ |  ------ |
| voltage | number|  | VDD voltage in volts |

### Example call
```lua
vdd = sys.gVDD()
```

## sys.gBoardTempK()
### Description
Get reading of the on board temperature sensor in kevin.
### Parameters
nil
### Return value

| Name | Type | Range | Usage |
| ------ | ------ | ------ |  ------ |
| temperature | number|  | Temperature in kevin |

### Example call
```lua
temp = sys.gBoardTempK()
```
## sys.verToString()
### Description
Convert a `naïve` format version into human-readable string.
### Parameters

| Name | Type | Range | Usage |
| ------ | ------ | ------ |  ------ |
| version | number|  | `naïve` |

### Return value

| Name | Type | Range | Usage |
| ------ | ------ | ------ |  ------ |
| readable | string|  | Converted human-readable string |

### Example call
```lua
print(sys.verToString(10000))
```
## sys.reset()
### Description
Perform a system reset.
### Parameters
nil
### Return value
nil
### Example call
```lua
sys.reset()
```

## sys.gByteCode()
### Description
Convert a input `*.lua` source file into `*.lc` bytecode file.
The output is in the same directory with the same name except the extension name is changed into `lc`.
### Parameters

| Name | Type | Range | Usage |
| ------ | ------ | ------ |  ------ |
| <path> | string|  | Path of the source file |
| [option] | number| `sys.STRIP_DEBUG_INFO` `sys.RESERVE_DEBUG_INFO`| Optional parameter to specify if debug info is stripped. The default is `sys.STRIP_DEBUG_INFO`|

### Return value
nil
### Example call
```lua
sys.gByteCode("0:/lua/user/UI_Demo.lua")
```
## Example Code
```lua
--[[This is a demo for sys APIs. The output will be on the terminal.

    Version: 191111
    Author:  yanke928]]

print("Hardware Version:",sys.verToString(sys.gHWVer()))
print("Software Version:",sys.verToString(sys.gFWVer()))
print("Lua API Version: ",sys.verToString(sys.gLuaAPIVer()))
print("Is USB Powered:  ",sys.gIsUSBPowered())
print("System Tick:     ",sys.gTick())
print("Total Heap:      ",sys.gTotalHeap())
print("Free Heap:       ",sys.gFreeHeap())
print("Free Heap Ever:  ",sys.gFreeHeapEver())
print("VDD Voltage:     ",sys.gVDD())
print("Board Temp Kel:  ",sys.gBoardTempK())
--[[ call sys.reset() to reboot.]]

os.exit()
```