### Sample OpenProtocol tool configuration

Source: https://haller-erne.github.io/Docusaurus/ogs/tools/openprotocol

An example configuration for channel 01, demonstrating both shared and channel-specific parameters.

```ini
[OPENPROTO]  
# Shared/default parameters  
PORT=4545  
# Channel/Tool 1 parameters  
CHANNEL_01=10.10.2.163  
CHANNEL_01_TYPE=NEXO  
CHANNEL_01_CHECK_TIME_ENABLED=1  
CHANNEL_01_CURVE_REQUEST=1  
```

--------------------------------

### Implement Web Request Handler

Source: https://haller-erne.github.io/Docusaurus/ogs/v3/lua/webserver

Example implementation of a request handler function and its registration.

```lua
local function handlerfn(reqpath, reqparams, verb, body)  
    -- process the request, return the response object (or nil  
    -- if this request is not handled)   
    return nil  
end  
-- Register a LUA function to be called whenever a web request to /api/lua  
-- is made  
Browser.RegMsgHandler('/api/lua', handlerfn)  
```

--------------------------------

### JavaScript Implementation for Browser View

Source: https://haller-erne.github.io/Docusaurus/ogs/v3/lua/webbrowser

Example of setting up the OGS object and implementing functions to receive calls from LUA.

```javascript
<!DOCTYPE html>  
<html >  
</html>  
<body>  
<!-- whatever content is in the page -->  
</body>  
  
<script>  
// Create the OGS object and implement the callbacks/events  
OGS = {};		  
OGS.onInit = function(url) {  
	// if we get here, everyhing is initialized, so now send the 'hello' message  
	OGS.SendCmd('hello!');  
}  
OGS.myFunction = function(params) {  
	// This function was called from LUA code  
	console.log("OGS.myFunction called!", params);  
	// Now call back into OGS and return a complex object  
	var retval = { cmd: 'test', params: { p1: 1, p2: 'string' } };  
	OGS.SendCmd(JSON.stringify(retval));  
}  
</script>  
```

--------------------------------

### Initialize the LUA debugger backend

Source: https://haller-erne.github.io/Docusaurus/ogs/appnotes/debugging

Include this line at the top of your project's config.lua to start the debugger backend.

```lua
    require('lua-local-debugger')  
```

--------------------------------

### LUA Tool Driver Interface Implementation

Source: https://haller-erne.github.io/Docusaurus/ogs/v3/lua/customtools

Full implementation example including init, execute, and enable interface functions for handling tool events.

```lua
-- My custom LUA tool driver  
local _M = {  
	type = 'MyCustomTool',     -- type id (must match the DRIVER= in INI file)  
}  
local helpers = require('lua_tool_helpers')  
  
-------------------------------------------------------------  
-- Tool event: Initialize tool - called once during OGS init   
-- return 'OK' or some error text if the initialization failes.  
function _M.init(channel)  
    -- Decode/get my configuration (from station.ini)  
    local cfg = {  
        ComPort = channel.ini_params.COM_PORT,      -- COM port  
    }  
    -- Do whatever is needed to initialize your driver  
    -- ...  
  	channel.cfg = cfg         -- store the channels config data  
    return 'OK'               -- init successfully done  
end  
  
----------------------------------------------------------------------------  
-- Tool event: Cyclically called while the tool is enabled  
-- return the tool task state  
function _M.execute(channel)  
    -- Check for tool finished  
    local ResultData = _M.GetResultData() -- must be implemented!  
    if ResultData == nil then       -- no data available from the tool  
        return channel.task_state   -- wait more.  
    end  
    if ResultData.Error then        -- some error occurred  
        return lua_task_fault       -- return an error code  
    end  
    if ResultData.Data then         -- received data  
        -- Build a result data table and notify the OGS core   
        local values = {  
            ResultData.torque,          -- M1 actual value  
            ResultData.angle,           -- M2 actual value  
            ResultData.t_min,           -- M1 min  
            ResultData.t_max,           -- M1 max  
            0.0,                        -- M2 min  
            0.0                         -- M2 max  
        }  
        local error_code = helpers.get_code_from_limits(ResultData.torque, ResultData.t_min, ResultData.t_max)  
        lua_tool_result_response(channel.tool, error_code, 0, '2A', values)  
        return lua_task_completed  
    end  
    return channel.task_state       -- wait more.  
end  
  
-------------------------------------------------------------  
-- Tool event: Called whenever the tool is to be enabled  
-- @ output: true|false  - tool enabled/not enabled   
--                         (will be called again until enabled!)  
function _M.enable(channel)  
    local cfg = channel.cfg     -- access the channel config data  
    -- Do whatever is needed  
    return true                 -- tool is enabled  
end  
  
-------------------------------------------------------------  
-- register this tool with OGS (heLuaTool.dll)  
helpers.register_tool(_M)  
-- return the module  
return _M  
```

--------------------------------

### Configure station.ini for Lua tools

Source: https://haller-erne.github.io/Docusaurus/ogs/v3/lua/customtools

Example configuration for enabling the Lua tool DLL and defining a custom tool channel in station.ini.

```ini
[TOOL_DLL]  
heLuaTool.dll=1 ; (1)!  
  
[CHANNELS]  
20=LuaTool_MyCustomTool ; (2)!  
  
[LuaTool_MyCustomTool]  
Driver=heLuaTool  
TYPE=MyCustomTool  
; additional LUA too specific parameters can follow  
```

--------------------------------

### ble.scan_start(callback, filter)

Source: https://haller-erne.github.io/Docusaurus/ogs/v3/lua/bluetooth-le

Starts listening for BLE advertisement frames. The scan runs for 10 seconds by default or until scan_stop is called.

```APIDOC
## ble.scan_start(callback, filter)

### Description
Starts listening for BLE advertisement frames. The callback function is invoked for each frame received and when the scan stops.

### Parameters
- **callback** (function) - Required - Function called with a table of device details or nil when the scan stops.
- **filter** (int) - Optional - The 16-bit short UUID of the service to filter by. Defaults to 0xFCD2 (BTHome) if nil. Set to -1 to receive all frames.
```

--------------------------------

### post_async(url, body, auth_bearer_token, user, pass)

Source: https://haller-erne.github.io/Docusaurus/ogs/libs/lua-net

Starts an asynchronous POST request.

```APIDOC
## post_async(url: string, body: string = nil, auth_bearer_token: string = nil, user: string = nil, pass: string = nil)

### Description
Starts an async post request. Returns a handle for polling or aborting.

### Returns
- **handle** (number) or **nil**
```

--------------------------------

### Configure VSCode launch settings for OGS

Source: https://haller-erne.github.io/Docusaurus/ogs/appnotes/debugging

Add this configuration to .vscode/launch.json to enable the local LUA debugger. Replace <instdir> with the actual installation path of OGS.

```json
    {  
        "version": "0.2.0",  
        "configurations": [  
            {  
                "name": "OGS (local lua debugger)",  
                "type": "lua-local",  
                "request": "launch",  
                "program": {  
                    "command": "<instdir>/monitor.exe",  
                    "communication": "stdio"  
                },  
                "args": [  
                ],  
                "scriptRoots": [  
                    "<instdir>",  
                    "<instdir>/lualibs",  
                ],  
                "stopOnEntry": true,  
                "pullBreakpointsSupport": true,  
                "cwd": "<instdir>",  
                "verbose": false,  
                "integratedTerminal": true  
            }  
        ]  
    }  
```

--------------------------------

### Execute locate.exe commands

Source: https://haller-erne.github.io/Docusaurus/ogs/dataoutput/printout

Examples of generating PDF reports or printing reports based on station database data using locate.exe.

```batch
@rem Generate a pdf report and show it. Use INT_VAR1=12345 and STR_VAR2=YES  
locate.exe [db=station.fds][sn=123456][form=label.fr3][show=YES][INT_VAR1=12345][STR_VAR2=YES][output=C:\\tmp\\mumu.pdf]  
  
@rem Print the same report on printer KYOCERA FS1900. Use INT_VAR1=12345 and STR_VAR2=YES  
locate.exe [db=station.fds][sn=123456][form=label.fr3][show=YES][INT_VAR1=12345][STR_VAR2=YES][output=KYOCERA FS1900]  
  
```

--------------------------------

### Configure Doga Tool Channels

Source: https://haller-erne.github.io/Docusaurus/ogs/tools/non-openprotocol/doga-wifi

Example configuration for a Doga tool on channel 06, specifying the IP address and custom Modbus/TCP port.

```ini
; Setup Doga tool channels  
[DOGA]  
; Define communication parameters for OGS tool #6  
CHANNEL_06=10.10.2.112  
CHANNEL_06_PORT=5000  
; ... more tools ...  
```

--------------------------------

### Implement BLE Scan Callback

Source: https://haller-erne.github.io/Docusaurus/ogs/v3/lua/bluetooth-le

Example implementation of a scan callback that filters for a specific device ID and restarts the scan upon completion.

```lua
local cbFn = nil  
local myDeviceId = ''  
  
-- Callback function, when a BLE advertisment is received  
local function onScan() end  
onScan = function(tbl)  
	if tbl == nil then  
		-- scan finished, restart scanning  
        ble.scan_start(cbFn, 0xFCD2)  
	else  
		XTRACE(16, "scan device found: id="..(tbl.id or ''))  
        if tbl.id ==  myDeviceId then  
            -- this is our key!  
            local bthome = tbl.bthome  
            if cbFn then  
                cbFn(tbl)  
            end  
            ble.scan_stop()  
        end  
	end  
end  
  
-- Call this function to start scanning, until an advertisment  
-- for the given device-id and the service 0xFCD2 is received,  
-- If a matching response is received, the callback function   
-- provided in the parameter will be called and the scan will stop.  
function Scan(deviceId, callback)  
    -- store the callback function locally  
    cbFn = callback  
    -- keep the device id  
    myDeviceId = deviceId  
    -- start (asynchronously) scanning for btHome devices (service UUID = 0xFCD2)  
    ble.scan_start(cbFn, 0xFCD2)  
end  
```

--------------------------------

### get(url, user, pass)

Source: https://haller-erne.github.io/Docusaurus/ogs/libs/lua-net

Executes a blocking GET request for the given URL.

```APIDOC
## get(url: string, user: string = nil, pass: string = nil)

### Description
Executes a blocking get request for the given URL. If the server returns status 200, the response is considered valid.

### Parameters
- **url** (string) - Required - The target URL.
- **user** (string) - Optional - Username for basic authentication.
- **pass** (string) - Optional - Password for basic authentication.

### Returns
- **data** (string), **status** (number), **statustext** (string), **data** (string) or **nil**, **status** (number), **statustext** (number)
```

--------------------------------

### Start service routine 125

Source: https://haller-erne.github.io/Docusaurus/ogs/tools/openprotocol/opexplus

Initiate the service routine for changing the operating mode.

```text
sr 125  
```

--------------------------------

### Configure FTP client for traceability

Source: https://haller-erne.github.io/Docusaurus/ogs/tools/openprotocol/gwk

Sets up the traceability output for tools in the [FTP_CLIENT] section.

```ini
[FTP_CLIENT]  
Enabled=1  
;...   
; (more settings)  
;...   
; Parameters for each channel:  
CHANNEL_06_INFO={ "ChannelName": "WS010|AC_PF6000", "location name": ["Tool", "Line 2", "WS010", "default", "", "", ""] }  
```

--------------------------------

### put_async(url, body, auth_bearer_token, user, pass)

Source: https://haller-erne.github.io/Docusaurus/ogs/libs/lua-net

Starts an asynchronous PUT request.

```APIDOC
## put_async(url: string, body: string = nil, auth_bearer_token: string = nil, user: string = nil, pass: string = nil)

### Description
Starts an async put request. Returns a handle for polling or aborting.

### Returns
- **handle** (number) or **nil**
```

--------------------------------

### init(channel: table)

Source: https://haller-erne.github.io/Docusaurus/ogs/v3/lua/customtools

Initializes a tool registered in station.ini. Returns 'OK' on success or an error message.

```APIDOC
## init(channel: table)

### Description
Called once for each tool registered in station.ini. The channel table contains tool configuration and initialization parameters.

### Parameters
- **channel** (table) - Required - Contains channel.tool and channel.ini_params.

### Returns
- **result** (string) - 'OK' on success, otherwise an error message.
```

--------------------------------

### Configure JNA Tightening Strategy

Source: https://haller-erne.github.io/Docusaurus/ogs/tools/non-openprotocol/stahlwille

Example configuration for a Joint Angle (JNA) strategy.

```JSON
PRG_02={ "name":"WiFi-JNA", "type":"JNA", "mode":"clic", "unit":"Nm", "elen":100.0, "t_thr":6.0, "a_min":5, "a_tgt":15, "a_max":25 }  
```

--------------------------------

### Configure JNT Tightening Strategy

Source: https://haller-erne.github.io/Docusaurus/ogs/tools/non-openprotocol/stahlwille

Example configuration for a Joint Torque (JNT) strategy.

```JSON
PRG_01={ "name":"WiFi-JNT", "type":"JNT", "mode":"clic", "unit":"Nm", "elen":100.0, "t_min":6.1, "t_tgt":6.5, "t_max":7.5 }  
```

--------------------------------

### EventLog.Init()

Source: https://haller-erne.github.io/Docusaurus/ogs/v3/lua/eventlog

Called during OGS startup to initialize the event logging system. Must return true to enable event logging.

```APIDOC
## EventLog.Init()

### Description
Initializes the EventLog interface during OGS startup. This function must be defined and return true to enable the reception of events.

### Returns
- **boolean** - Returns true to enable EventLog events.
```

--------------------------------

### Define appl_start parameter format

Source: https://haller-erne.github.io/Docusaurus/ogs/tools/openprotocol/sys350-ke350

The appl_start parameter maps bolts to spindles using a group name and a sequence number.

```text
appl_start = `<group><sequence>`
```

--------------------------------

### LUA to JavaScript Communication

Source: https://haller-erne.github.io/Docusaurus/ogs/v3/lua/webbrowser

Example of registering a message handler and executing a JavaScript function from LUA.

```lua
-- define which browser view to use  
local instance = 'StartView'  
  
-- define a function to be called from JavaScript  
local callbackfn = function(instance, msg)  
	XTRACE(16, "I am called from Javascript: msg=" .. msg)  
end  
  
-- Register (global) callback for the browser instance  
Browser.RegMsgHandler(instance, callbackfn)  
  
-- Build a JavaScript command, call the function "OGS.myFunction" with  
-- some JSON text  
local param = '{ "cmd": "showmessage" }'  
local command = "OGS.myFunction("..param..");"  
-- Call the JavaScript function in the browser instance  
Browser.ExecJS_nonblocking(instance, command)  
```

--------------------------------

### open(path) / open(vid, pid)

Source: https://haller-erne.github.io/Docusaurus/ogs/libs/lua-hid

Opens a HID device connection using either a path or a VID/PID pair.

```APIDOC
## open(string path) / open(number vid, number pid)

### Description
Opens a HID device using a path name or a vid,pid pair. Returns a HID device object on success.

### Parameters
- **path** (string) - Optional - Device path
- **vid** (number) - Optional - Vendor ID
- **pid** (number) - Optional - Product ID

### Returns
- **HidDevice** - Device object or nil on failure
```

--------------------------------

### Example JSON event output

Source: https://haller-erne.github.io/Docusaurus/ogs/v3/lua/eventlog

Represents the structure of a generated JSON message for a login event.

```json
{
    "type":3,
    "timestamp":"2023-03-31 09:56:00",
    "name":"USER_LOGON",
    "status":0,
    "user1":"U40003ACC4D",
    "user2":"",
    "login":"login"
}
```

--------------------------------

### Navigate Browser Instance

Source: https://haller-erne.github.io/Docusaurus/ogs/v3/lua/webbrowser

Initiates navigation to a specified URL for a given browser instance.

```lua
Browser.Navigate(instance, url)
```

```lua
-- Navigate the StartView browser to https://www.my-url.com/mypage  
Browser.Navigate('StartView', 'https://www.my-url.com/mypage')
```

--------------------------------

### Configure JAT Tightening Strategy

Source: https://haller-erne.github.io/Docusaurus/ogs/tools/non-openprotocol/stahlwille

Example configuration for a Joint Angle + Torque (JAT) strategy.

```JSON
PRG_04={ "name":"WiFi-JAT", "type":"JAT", "mode":"clic", "unit":"Nm", "elen":100.0, "t_min":6.1, "t_tgt":6.5, "t_max":7.5, "t_thr":5.0, "a_min":5, "a_tgt":15, "a_max":25 }  
```

--------------------------------

### Configure JTA Tightening Strategy

Source: https://haller-erne.github.io/Docusaurus/ogs/tools/non-openprotocol/stahlwille

Example configuration for a Joint Torque + Angle (JTA) strategy.

```JSON
PRG_03={ "name":"WiFi-JTA", "type":"JTA", "mode":"clic", "unit":"Nm", "elen":100.0, "t_min":6.1, "t_tgt":6.5, "t_max":7.5, "t_thr":5.0, "a_min":5, "a_tgt":15, "a_max":25 }  
```

--------------------------------

### PowerShell commandlet usage

Source: https://haller-erne.github.io/Docusaurus/ogs/libs/lua-dpapi

Example of invoking a PowerShell script to encrypt data from the command line.

```powershell
powershell -file myscript.ps1 -data "MySuperSecretPassword"  
```

--------------------------------

### Show Web Browser Instance

Source: https://haller-erne.github.io/Docusaurus/ogs/v3/lua/webbrowser

Navigates a browser instance to a URL and ensures it is visible.

```lua
local oldUrl = Browser.Show(instance, url)  
```

```lua
-- Make the SidePanel visible, set the width to 25% and navigate the  
-- web browser to https://www.my-url.com/mypage  
local oldUrl = Browser.Show('SidePanel', 'https://www.my-url.com/mypage', 0, '25')  
```

--------------------------------

### Override Filename with Lua

Source: https://haller-erne.github.io/Docusaurus/ogs/dataoutput/xmlfile

Example of wrapping the default GetXMLFile function to customize the output filename format.

```lua
-- Store the original function in a local variable  
local old_GetXMLFile = GetXMLFile  
  
-- Define the new function (override the original one)  
function GetXMLFile(idcode, model)  
  
	-- Call the "original" function to get the XML data  
	local old_filename, old_filecontent = old_GetXMLFile(idcode, model)  
  
	-- Create a new filename as "<idcode>-<YYYY><MM><DD>T<HH><mm><ss>.xml"  
	local t = os.date('*t')  
	local t_as_str = string.format('%04d%02d%02dT%02d%02d%02d', t.year,t.month, t.day, t.hour,t.min,t.sec)  
	local new_filename = string.format('%s-%s.xml', idcode, t_as_str)  
  
	-- Return the "new" filename and the "old" file content  
    return new_filename, old_filecontent  
end  

```

--------------------------------

### Configure OPC-UA Client

Source: https://haller-erne.github.io/Docusaurus/ogs/libs/lua-opcua

Sample configuration file for the OPC-UA client interface.

```ini
[OPCUA_CLIENT]  
; OPCUA connection URL:  
SERVER_URL=opc.tcp://192.168.0.1:4840  
SERVER_USERNAME=OGSInterfaceUser  
SERVER_PASSWORD=OGSPassword1  
SERVER_SECURITY=1  
SERVER_CERT_FILE=d:/test_cert.der  
SERVER_CERT_KEY=d:/test_key.der  
; Namespace of variables:  
SERVER_NS=3  
; Define the full path for the variables												   
TO_PLC_VAR=""DB_OGS_V3"."st01"."line"."ogs_to_plc""  
TO_OGS_VAR=""DB_OGS_V3"."st01"."line"."plc_to_ogs""  
DEBUG=2  
```

--------------------------------

### Execute Report via LUA

Source: https://haller-erne.github.io/Docusaurus/ogs/dataoutput/printout

Demonstrates how to format a command line and execute a print process using the CreateProcess function.

```lua
-- prepare the command line  
local fmt = 'heLabelPrinter.exe [form=%s][show=NO][MN=%s][SN=%s][output=%s]'  
local cmd = string.format('label.fr3', 'MNum', 'SNum', 'output.pdf')  
  
-- execute the command (with a hidden window)  
local err = CreateProcess(cmd, 134217728) -- CREATE_NO_WINDOW flag 0x8000000  
if err then  
	SetLuaAlarm('PRINTER', 'Print failed! Error='..param_as_str(err))  
end	  
```

--------------------------------

### Define Robot Kinematics with URDF

Source: https://haller-erne.github.io/Docusaurus/ogs/tools/positioning/positioning-robot-urdf

Example of a robot URDF fragment defining links, joints, and mesh references.

```xml
<robot name="my_arm">  
    <link name="base_link">  
        <visual>  
            <geometry>  
                <mesh filename="meshes/base_link.stl" scale="0.001 0.001 0.001" />  
            </geometry>  
        </visual>  
    </link>  
  
    <joint name="base_rotation" type="revolute">  
        <parent link="base_link" />  
        <child link="arm_link" />  
        <origin xyz="0 0 1.5" rpy="0 0 0" />  
        <axis xyz="0 0 1" />  
        <limit lower="-3.14" upper="3.14" />  
    </joint>  
  
    <link name="arm_link">  
        <visual>  
            <geometry>  
                <mesh filename="meshes/arm_link.stl" scale="0.001 0.001 0.001" />  
            </geometry>  
        </visual>  
    </link>  
  
    <!-- Fixed joint to tool (no sensor needed) -->  
    <joint name="tool_mount" type="fixed">  
        <parent link="arm_link" />  
        <child link="tool_link" />  
        <origin xyz="0 0 -0.3" rpy="0 0 0" />  
    </joint>  
  
    <link name="tool_link" />  
</robot>  
```

--------------------------------

### Execute heLabelPrinter.exe commands

Source: https://haller-erne.github.io/Docusaurus/ogs/dataoutput/printout

Examples of generating PDF reports or printing directly to a specified printer using heLabelPrinter.exe.

```batch
@rem Generate a pdf report and show it. Use INT_VAR1=12345 and STR_VAR2=YES  
heLabelPrinter.exe [form=label.fr3][show=YES][INT_VAR1=12345][STR_VAR2=YES][output=C:\\tmp\\mumu.pdf]  
  
@rem Print the same report on printer KYOCERA FS1900. Use INT_VAR1=12345 and STR_VAR2=YES  
heLabelPrinter.exe [form=label.fr3][show=YES][INT_VAR1=12345][STR_VAR2=YES][output=KYOCERA FS1900]  
  
```

--------------------------------

### Test User Login and Permissions

Source: https://haller-erne.github.io/Docusaurus/ogs/appnotes/firebird-security

Commands to verify user login tokens and check effective database roles.

```bash
runas /noprofile /user:ogs_editor cmd.exe
```

```bash
[ogs_editor]> isql -tr <dbhost>:<dbname>
```

```bash
C:\Program Files\Firebird\Firebird_4_0>isql -tr 127.0.0.1:test01  
Database: 127.0.0.1:test01, User: PUBLIC, Role: DB_ROLE_WRITER  
SQL>
```

```sql
SQL> select part from part;
```

```sql
SQL> select part from part;  
  
            PART  
    ============  
            59  
            60  
            ...  
SQL>
```

--------------------------------

### Enable URDF 3D Viewer in Configuration

Source: https://haller-erne.github.io/Docusaurus/ogs/tools/positioning/positioning-robot-urdf

Include the startpage_urdf module in the project requirements and set the billboard property to enable the interactive 3D robot visualization.

```lua
requires = {  
    "lib.positioning",  
    "startpage_urdf",           -- 3D URDF robot viewer  
    "station_io",  
    -- ...  
}  
current_project.billboard = 'startpage_urdf.html'
```

--------------------------------

### Detect and Read Smartcards

Source: https://haller-erne.github.io/Docusaurus/ogs/libs/lua-ostools

Demonstrates how to initialize readers, monitor for card insertion/removal events, and read the serial ID of a connected card.

```lua
local scard = require('luaostools.scard')           -- load our library  
  
local gReaders = nil  
local gCards = {}  
-- return status, id  
local function GetCardId()  
    if not gReaders then  
        local readers, err = scard.GetReaders()  
        if readers == nil then  
            return nil, 'no reader available'  
        end  
        print("Smartcard Readers found:")  
        for _,reader in pairs(readers) do  
            print(string.format('  Reader %s', reader))  
        end  
        gReaders = readers  
    end  
    local data, err = scard.GetStatusChange()  
    if data then  
        for k,v in pairs(data) do  
            if v.handle and v.handle ~= 0 then  
                -- card is plugged  
                print(string.format('[%s] Card plugged: State %08Xh', k, v.state))  
                local status, id, data = scard.ReadCardSerial(k)  
                if status == 0x9000 then  
                    -- local raw = basexx.to_hex(data)  
                    print(string.format('       ID = "%s" (State %08Xh)', id, status))  
                    gCards[k] = id  
                    return true, id  
                else  
                    return nil, 'error reading card'  
                end  
            else  
                -- card is unplugged  
                local oldId = gCards[k] or ''  
                if oldId == '' then  
                    -- was no card before  
                    return nil, 'initial card remove event'  
                end  
                print(string.format('[%s] Card "%s" removed', k, oldId))  
                return false, oldId  
            end  
        end  
    end  
end  
  
-- run an endless test loop...  
while true do  
    GetCardId()  
end  
```

--------------------------------

### Browser.Show

Source: https://haller-erne.github.io/Docusaurus/ogs/v3/lua/webbrowser

Activates the web browser and navigates to the specified URL.

```APIDOC
## Browser.Show(url)

### Description
Activate (show) the webbrowser and navigate to the specified url.

### Parameters
- **url** (string) - The URL to navigate to upon showing.
```

--------------------------------

### init()

Source: https://haller-erne.github.io/Docusaurus/ogs/libs/lua-hid

Initializes the LuaHID library. This must be called before any other function.

```APIDOC
## init()

### Description
Initializes the LuaHID library. Returns true on success, nil on failure.

### Returns
- **boolean** - Success status
```

--------------------------------

### Configure Station Database Settings

Source: https://haller-erne.github.io/Docusaurus/ogs/appnotes/userdb-heusermanager

Define the database connection and logon behavior in the station.ini file.

```ini
[USER]  
  
; Define, if users should be logged out automatically after a configured   
; inactivity time (given in minutes). If autologoff is defined and set   
; to a nonzero value, users will be loggerd off automatically.  
; Note, that the autologon user will never be logged out automatically!  
autologoff=10  
  
; Defines a connection string (may be encrypted, see docs) to connect to   
; the heUserManager database for centralized login information.  
; If not defined or empty, then only local logon (password/rfid) is   
; (by default) available.  
; NOTE: you should encrypt the connection string or use active directory  
;       authentication (Trusted_Connection=yes) to avoid storing  
;       credentials in plain text!  
logonserver=Provider=SQLOLEDB.1;Persist Security Info=False;User ID=sys3xx;Password=sys3xx;Initial Catalog=heUserManager01;Data Source=QUALITYR  
  
; Defines an additional user group parameter to check when querying the  
; database.   
; If not defined or empty, then additional group membership is not checked.  
logongroup=  
  
; Defines the application ID to use when querying the heUserManager  
; database. If not defined or empty, then application rights/roles are not  
; used.   
; Leave empty to use the "old" behaviour (users OGSlevel is used instead  
; application rights)  
logonappid=heOGS-line1  
  
; Defines, if the user cannot log on, if he is already logged on at  
; another station. This requires that the heUserManager database is used  
; (i.e. logonserver is defined) and that the database has the DB_LOCK_GET,  
; DB_LOCK_RELEASE and DB_LOCK_REQUEST procedures  
logonlock=1  
```

--------------------------------

### Implement Tool Driver Formatting with Helpers

Source: https://haller-erne.github.io/Docusaurus/ogs/v3/lua/customtools

Use the lua_tool_helpers module to read formatting configurations from station.ini and implement the required driver interface functions.

```lua
local helpers = require('lua_tool_helpers')  
local _M = {  
	type = 'MyLuaTool',     -- type identifier (as in INI file)  
}  
  
-------------------------------------------------------------  
-- Initialize the driver and read the parameter section  
function _M.init(channel)  
	-- local (tool instance specific) parameters  
	local cfg = {  
        -- Initialize the parameters for formatting  
        fmt = helpers.read_fmt_config(channel)  
    }  
    channel.cfg = cfg  
    return 'OK'  
end  
  
-------------------------------------------------------------  
-- Get the tool specific measurement units   
-- @param tool: channel number as configured in station.ini  
-- @return:  applicable only for the first two values (from 6)  
_M.get_tool_units = function(tool)  
	local channel = _M.channels[tool]  
    return helpers.get_tool_units(channel, channel.cfg.fmt)  
end  
-- Get the tool specific result string  
_M.get_tool_result_string = function(tool)  
	local channel = _M.channels[tool]  
    return helpers.get_tool_result_string(channel, channel.cfg.fmt)  
end  
-- Get the tool specific footer string  
_M.get_footer_string = function(tool)  
	local channel = _M.channels[tool]  
    return helpers.get_footer_string(channel, channel.cfg.fmt)  
end  
-- Get the tool specific program name  
_M.get_prg_string = function(tool)  
	local channel = _M.channels[tool]  
    return helpers.get_prg_string(channel, channel.cfg.fmt)  
end  

```

--------------------------------

### Define BLE Data Structures

Source: https://haller-erne.github.io/Docusaurus/ogs/v3/lua/bluetooth-le

Example of the data structure returned by the BLE scan callback, including BTHome decoded fields and raw advertisement data.

```lua
---@class BleBtHomeData  
---@field flags integer BTHome flags 0x40 = cyclic bthome, 0x44 = trigger bthome  
---@field seq integer Sequence number (to detect multiple frames, e. g. increments once per button press)  
---@field battery integer Battery level (0-100)  
---@field action integer Action code (0 = none, 1 = click, 2 = doubleclick, ...)  
---@field button string decoded action ('press', 'double_press', ...)  
  
---@class BleAdvertismentData  
---@field id string Unique MAC address of the BLE device  
---@field service integer 16-Bit service id (32/128-bit IDs are only provided in the response data)  
---@field name string Local device name (if provided, else empty string)  
---@field rssi integer The RSSI level  
---@field response table<integer,string> The actual advertisment data as key/value (binary string) data  
---@field bthome BleBtHomeData|nil If the device is a bthome device, then decoded data here  
  
-- This is what is typically received  
---@type BleAdvertismentData  
local sample = {  
    id = '7CC6B6653AA9',  
    service = 0xFCD2,  
    name = '',  
    rssi = -55,  
    response = { [22] = '', [1] = '' },  
    bthome = {  
        flags = 0x44,  
        battery = 100,  
        seq = 3,  
        action = 1,  
        button = 'press'  
    }  
}  
```

--------------------------------

### Mirror custom inputs to outputs in LUA

Source: https://haller-erne.github.io/Docusaurus/ogs/tools/openprotocol/sys350-cs351

Demonstrates how to cyclically exchange IO data with an OpenProtocol tool and mirror input signals to outputs. Requires setting EXTERNAL_IO_OFFSET in station.ini.

```lua
-- station_io.lua  
  
-- Requirements:  
-- * Define Channel_01 as OpenProtocol tool (CS351/KE350) in station.ini  
-- * Set EXTERNAL_IO_OFFSET=2 in [OPENPROTO] section  
  
-- Handle the OpenProtocol IOs  
local prev_output = nil  
local prev_input = nil  
local output = 0  
local channel = 1           -- use Channel_01   
local tool_error = nil  
  
-- StatePoll is called cyclically  
local function OnStatePoll(info)  
  
    local wf = info.Workflow  
  
    -- Cyclically update the OpenProtocol I/O data  
    local input, err = ToolIOExchange(channel, output)  
    if err then  
        if not tool_error then  
            SetLuaAlarm('ToolIO', -2, param_as_str(err))  
            XTRACE(1, param_as_str(err))  
            tool_error = true  
        end  
        return nil  
    else  
        if tool_error then  
            ResetLuaAlarm('ToolIO')  
            XTRACE(8, 'Tool3 IO running!')  
            tool_error = nil  
        end  
        if output ~= prev_output or input ~= prev_input then  
            XTRACE(16, string.format('IO changed. Input: %02Xh, Output: %02Xh', input, output))  
            prev_output = output  
            prev_input  = input  
        end  
    end  
  
    -- mirror input to output - note: custom inputs are the high byte!  
    output = input / 256  
  
end  
  
if StatePollFunctions ~= nil then  
	StatePollFunctions.add(OnStatePoll)  
end
```

--------------------------------

### Loading LuaOSTools libraries

Source: https://haller-erne.github.io/Docusaurus/ogs/libs/lua-ostools

Load the security and scard submodules to access their respective Windows API functions.

```lua
-- Load the OSTools security library:  
local security = require('luaostools.security')  
  
-- Load the OSTools scard library:  
local scard = require('luaostools.scard')  
```

--------------------------------

### Initialize SYSDBA user

Source: https://haller-erne.github.io/Docusaurus/ogs/appnotes/firebird-security

Steps for creating the SYSDBA user via an interactive isql session.

```text
1. Stop the Firebird server. Firebird caches connections to the security database aggressively. The presence  
of server connections may prevent isql from establishing an embedded connection.  
2. In a suitable shell, start an isql interactive session, opening the employee database via its alias:  
    > isql -user sysdba employee  
3. Create the SYSDBA user:  
    WARNING! Do not just copy and paste! Generate your own strong password!  
  
    SQL> create user SYSDBA password 'StrongPassword';  
    SQL> exit;  
  
    WARNING! Do not just copy and paste! Generate your own strong password!  
  
4. To complete the initialization, start the Firebird server again. Now you will be able to perform a network  
login to databases using login SYSDBA and the password you assigned to it.  

```

--------------------------------

### Configure FTP Traceability Output

Source: https://haller-erne.github.io/Docusaurus/ogs/dataoutput/traceability

Use the [FTP_CLIENT] section to enable FTP data transmission. Supports both standard FTP servers and Sys3xxGateway servers.

```ini
[FTP_CLIENT]  
; Set ENABLED=1 to enable traceability data output  
ENABLED=1  
; Set ReportSkippedOperations=1, if you want to see operators skip actions  
; in the traceability data output, else set to =0  
ReportSkippedOperations=1  
  
; Define the targets FTP (Sys3xxGateway) server IP-Address and port  
HostIP=10.80.59.252  
HostPort=21  
  
; In case of Sys3xxGateway(Qtrans) as FTP server use "Username=sys3xx" and  
; "Password=sys3xx". TargetFolderOnHost is not needed (ignored) then.  
Username=sys3xx  
Password=sys3xx  
  
; In case of standard FTP Server the "TargetFolderOnHost" parameter must   
; be set and is used as a base folder to store data.  
TargetFolderOnHost=  
```

--------------------------------

### Configure OpenProtocol Tool with ART Driver

Source: https://haller-erne.github.io/Docusaurus/ogs/tools/positioning

Define positioning settings in station.ini for an OpenProtocol channel using the ART tracking system.

```ini
[OPENPROTO]  
CHANNEL_01=192.168.1.42  
CHANNEL_01_TYPE=GWK  
CHANNEL_01_PORT=4002  
; --> this channel shall use ART positioning  
CHANNEL_01_POSITIONING=POSITIONING_ART_CH1  
  
; --> Connection between the CHANNEL_01 and the ART positioning system  
[POSITIONING_ART_CH1]  
; Define to use the AR.Tracking positioning system with this channel  
DRIVER=ART  
; Positioning timeout in milliseconds. Defines the grace time before enable  
; is removed for the tool, when leaving a position. If not set, defaults to 0.  
TIMEOUT=1000  
; Define the target tracker and tool adapter for this tool  
; Target-ID: this is the model of the target mounted to the tool. By default,  
; T1-T8 are provided, other targets can be defined in "targets.atti"-file   
TARGET_ID=T5  
; Target-Mount-ID: specify the adapter geometry, so the ART driver can calulate  
; the tool center point depending on where the target is mounted on the tool.  
; By default, "Rexroth ESA030G" and "GWK Operator Plus" are provided, custom  
; mounts may be added in "targetmounts.atti"  
TARGET_MOUNT_ID=Rexroth ESA030G  
; Default-length of the adapter mounted to the tool (tool center point)  
OFFSET_MM=0  
  
; --> common parameter required by the ART driver  
[POSITIONING_ART]  
; Define the IP-Address of the SmartTrack camera system  
IP=10.10.2.108  
; If you want to use custom targets or custom target_mounts, then you can  
; specify these in "targets.atti" and "targetmounts.atti" in the following  
; folder. If the folder is not specified, it defaults to the current projects  
; folder.  
;DB_FOLDER=  
; If you want to set the reference tracker, then add the name of the tracker here.  
; NOTE: the reference tracker must be configured through DTrack and *must* have  
;       then name "reference" or "referenz" (case insensitive) as part of the  
;       body name, else it will not be accepted.  
REFERENCE_TRACKER=Claw Target 21 Reference
```

--------------------------------

### Show the side panel via Lua

Source: https://haller-erne.github.io/Docusaurus/ogs/v3/lua/sidepanel

Use Browser.Show to make the side panel visible, set its width, and navigate to a specific URL.

```lua
-- Make the SidePanel visible, set the width to 25% and navigate the  
-- web browser to https://www.my-url.com/mypage  
local oldUrl = Browser.Show('SidePanel', 'https://www.my-url.com/mypage', 0, '25')  
```

--------------------------------

### Load Keyence Driver in config.lua

Source: https://haller-erne.github.io/Docusaurus/ogs/tools/misc/keyence-iv4

Required for OGS versions below V3.1.6 to include the camera driver in the project configuration.

```lua
-- add the shared folder (..\shared)  
OGS.Project.AddPath('../shared')  
  
requires = {  
    "barcode",  
    "user_manager",  
    "lua_tool_camera_keyence",      -- (1)  
}  
current_project.logo_file = '../shared/logo-rexroth.png'  
current_project.billboard = 'http://127.0.0.1:60000/billboard.html'  
```

--------------------------------

### Configure HTTP Traceability Output

Source: https://haller-erne.github.io/Docusaurus/ogs/dataoutput/traceability

Use the [HTTP_CLIENT] section to enable HTTP data transmission. Supports both http and https protocols.

```ini
[HTTP_CLIENT]  
; Set ENABLED=1 to enable traceability data output  
ENABLED=1  
; Set ReportSkippedOperations=1, if you want to see operators skip actions  
; in the traceability data output, else set to =0  
ReportSkippedOperations=1  
  
; Define the targets http (Sys3xxGateway) server URL endpoint  
; Note, that this also supports https!  
HostURL=http://myserver:8888/sys3xxgateway  
  
; Optionally set username/password for http basic authentication  
;Username=sys3xx  
;Password=sys3xx  
```

--------------------------------

### Configure OpenProtocol Channel Settings

Source: https://haller-erne.github.io/Docusaurus/ogs/tools/openprotocol/mtc

Define the tool communication parameters in the [OPENPROTO] section of station.ini, including IP, port, and feature flags.

```ini
[OPENPROTO]  
; Channel/Tool 1 parameters  
CHANNEL_01=10.10.2.184  
CHANNEL_01_PORT=4545  
CHANNEL_01_TYPE=MTF  
; Enable time synchronization   
CHANNEL_01_CHECK_TIME_ENABLED=1  
; Force CCW switch selection for rework/loosen  
CHANNEL_01_CCW_ACK=1  
; Enable cyclic enable check  
CHANNEL_01_CHECK_EXT_COND=1  
; To enable curve transmission, set to 1:  
; NOTE: requires a license!  
CHANNEL_01_CURVE_REQUEST=0  
```

--------------------------------

### Run Mosquitto Broker

Source: https://haller-erne.github.io/Docusaurus/ogs/appnotes/blegateway-minew-mg6

Execute the Mosquitto broker in verbose mode using the specified configuration file.

```bash
mosquitto.exe -v -c mosquitto.conf  

```

--------------------------------

### Configure SQL Server Connection String

Source: https://haller-erne.github.io/Docusaurus/ogs/appnotes/databanking

Add this configuration to the station.ini file to enable the databanking feature. Ensure the connection string uses the appropriate SQL Server driver and credentials.

```ini
[DATABANKING]  
ConnectionString=Provider=SQLNCLI11.1;User ID=<my-user>;Password=<my-pass>;Initial Catalog=<my-db>;Data Source=<my-server>\<my-instance>[,server-port]
```

--------------------------------

### Browser.Navigate

Source: https://haller-erne.github.io/Docusaurus/ogs/v3/lua/webbrowser

Loads a new URL in the specified web browser instance.

```APIDOC
## Browser.Navigate(url)

### Description
Loads a new URL in the web browser.

### Parameters
- **url** (string) - The URL to navigate to.
```

--------------------------------

### Configure firebird.conf for production

Source: https://haller-erne.github.io/Docusaurus/ogs/appnotes/firebird-security

Update firebird.conf to enforce trusted authentication and encrypted wire communication.

```ini
# Change the following settings  
  
DatabaseAccess = None  
AuthServer = Win_Sspi  
WireCrypt = Required  
WireCryptPlugin = ChaCha64, ChaCha  
```

--------------------------------

### Load Wenglor Driver in config.lua

Source: https://haller-erne.github.io/Docusaurus/ogs/tools/misc/wenglor-weqube

Required for OGS versions older than V3.1.6 to include the camera driver in the project configuration.

```lua
-- add the shared folder (..\shared)  
OGS.Project.AddPath('../shared')  
  
requires = {  
    "barcode",  
    "user_manager",  
    "lua_tool_camera_wenglor",      -- (1)  
}  
current_project.logo_file = '../shared/logo-rexroth.png'  
current_project.billboard = 'billboard.html'  
```

--------------------------------

### Configure XML output in station.ini

Source: https://haller-erne.github.io/Docusaurus/ogs/dataoutput/xmlfile

Define the destination directory and step result preferences in the [XML] and [GENERAL] sections of the station.ini file.

```ini
[GENERAL]  
; Define if the data output shall have all step results  
; or if only the final step results are used (default)  
;   
; Set SAVE_ONLY_LAST_STEP = 0 if you want all steps.  
SAVE_ONLY_LAST_STEP = 1  
  
[XML]  
; Define the workflow complete data output (save a result data file).  
; NOTES:  
; - If the DIRECTORY parameter is missing or empty, no file is generated.  
; - The [GENERAL] section RESULT_Ok=, RESULT_Nok=, RESULT_incomplete= define when a XML  
;   file is actually generated, e.g. if RESULT_incomplete=SKIP, no XML file will be  
;    generated, if a part is finished with incomplete status (like missing bolts).  
; - The generated file format/contents can be overriden by LUA code (see GetXMLFile())  
;  
; Define the output directory for generated part result reports (by default in XML format)  
DIRECTORY=C:\Daten  
```

--------------------------------

### Configure Tool DLL in station.ini

Source: https://haller-erne.github.io/Docusaurus/ogs/tools/non-openprotocol/doga-wifi

Load the Doga tool interface driver by adding it to the [TOOL_DLL] section of the station.ini file.

```ini
[TOOL_DLL]  
; Load and enable the Doga tool interface DLL:  
heDogaTool.dll=1  
; ... other tool drivers ...  
```