Skip to content

Module API

Jump to bottom
chrilith edited this page Oct 21, 2019 · 36 revisions

Passerelle adds some functionalities to Lua. here is the full list of the available methods.

API List

I have changed methods name to start with a lower case to match most Lua libraries. If you still want to use the upper case version you should use the legacy version of the module.

Internal Objects

Window

Bitmap

Constants

Version Information

Hardware Information

Obsolete Members

These methods will be remove in future versions of the module.

Saitek Related Methods

passerelle.addPage(model, index, page, activate)

Adds a new page identified by page to the model located at index and activates it if requested.

Parameter Type Description
model char(4) model code
index integer(1..n) index of the device of type model
page integer numerical value to identify the page
activate boolean should the page be activated

Compatibility: SFIP, X52P

passerelle.registerPageCallback(model, index, callback)

Adds a button state change notification callback to the model located at index. Pass nil to remove the callback.

Parameter Type Description
model char(4) model code
index integer(1..n) index of the device of type model
callback function name of the callback function in Lua

Compatibility: SFIP, X52P

passerelle.registerSoftButtonCallback(model, index, callback)

Adds a button state change notification callback to the model located at index. Pass nil to remove the callback.

Parameter Type Description
model char(4) model code
index integer(1..n) index of the device of type model
callback function name of the callback function in Lua

Compatibility: SFIP, X52P

passerelle.registerSoftButtonDownCallback(model, index, callback) -- >= v0.2

Adds a button pressed notification callback to the model located at index. Pass nil to remove the callback.

Parameter Type Description
model char(4) model code
index integer(1..n) index of the device of type model
callback function name of the callback function in Lua

Compatibility: SFIP, X52P

passerelle.registerSoftButtonUpCallback(model, index, callback) -- >= v0.2

Adds a button released notification callback to the model located at index. Pass nil to remove the callback.

Parameter Type Description
model char(4) model code
index integer(1..n) index of the device of type model
callback function name of the callback function in Lua

Compatibility: SFIP, X52P

passerelle.removePage(model, index, page)

Removes a previously added page identified by page from the model located at index.

Parameter Type Description
model char(4) model code
index integer(1..n) index of the device of type model
page integer numerical value to identify the page

Compatibility: SFIP, X52P

passerelle.setImage(model, index, page, image, data)

Tries to display the data on the page identified by page on the model located at index. For now only the GD module is supported. Data is obtained for instance using win:capture() or using gd2 with im:gd2Str(320, gd.GD2_FMT_RAW) on a gd.createTrueColor(320, 240).

Parameter Type Description
model char(4) model code
index integer(1..n) index of the device of type model
page integer numerical value to identify the page
image integer(1) index of the image (always 1)
data varying bitmap or lua string containing the image data

Compatibility: SFIP

passerelle.setImageFromFile(model, index, page, image, path[, stretch])

Tries to load the image (BMP or JPEG) located at path and display it on the page identified by page on the model located at index.

Parameter Type Description
model char(4) model code
index integer(1..n) index of the device of type model
page integer numerical value to identify the page
image integer(1) index of the image (always 1)
path string path to the image to be loaded
stretch boolean should the image be stretched

Compatibility: SFIP

passerelle.setLed(model, index, page, led, state)

Turns on or off a led at index led for the page identified by page on the model located at index.

Parameter Type Description
model char(4) model code
index integer(1..n) index of the device of type model
page integer numerical value to identify the page
led integer index of the led
state boolean should the led be turned on

Compatibility: SFIP, X52P

passerelle.setProfile(model, index, path) -- >= v0.2

Loads the profile located at path into the device. Pass nil to unload the profile.

Parameter Type Description
model char(4) model code
index integer(1..n) index of the device of type model
path string path to the profile to be loaded

Compatibility: X52P

passerelle.setString(model, index, page, line, str)

Tries to display the str at line on the page identified by page on the model located at index. The X52P can display up to 16 characters per line. If the text is longer, the line will scroll.

Parameter Type Description
model char(4) model code
index integer(1..n) index of the device of type model
page integer numerical value to identify the page
line integer(1..3) index of the string line
str string text to display

Compatibility: X52P

Utility Methods

passerelle.findWindow(class, name) -- >= v0.8

Tries to capture the client area of the window whose class name and window name match the specified strings. Coordinates are in percent of the client area dimensions. This method use the same parameters as the Windows FindWindow() function. To find the class name and the window name you can use WinLister.

Parameter Type Description
class string class name of the window
name string window name

Upon success, returns an new object representing the window.

WARNING: if your are capturing a window in a loop, the memory usage will grow very fast because the created bitmap objects are not collected immediately by Lua. Refer to the Lua documentation in order to know how to track and force garbage collection when needed.

passerelle.getNumDevices([model])

Retreives the number of available devices of type model or all available devices if model is not specified.

Parameter Type Description
model char(4) model code 

passerelle.getVersion() -- >= v0.5

Returns the current module version as a multiple result set. The table has the following structure.

Return Type Description
R1 string full version number
R2 integer major version
R3 integer minor version
R4 integer build version
R5 integer patch version

You can also use the new _NAME, _VERSION and _COPYRIGHT constants, added in v0.5.6, to get more version information.

passerelle.listen()

Convenience function to help testing the API in the Lua development environment. It will suspend the script execution so that callbacks can be evaluated easily.

passerelle.poll() -- >= 0.7

Executes the waiting callbacks if any.

passerelle.registerDeviceChangeCallback(callback) -- >= v0.2

Adds a device change notification callback. Pass nil to remove the callback.

Parameter Type Description
callback function name of the callback function in Lua 

passerelle.setMode(mode) -- >= v0.7

Sets the callback mode. You can choose between CBM_DIRECT, which is the legacy and default mode, CBM_EVENT for event-based polling and CBM_FSUIPC to work with FSUIPC (32-bit version only).

Parameter Type Description
mode integer model code

Using FSUIPC, the offset address is 0x736D. When you receive an event for this address you must call the poll() method to execute all the pending callbacks synchronously. The value has not specific meaning and should be ignored.

passerelle.sleep(time) -- >= 0.7

Convenience function to pause the execution for time milliseconds and reduce CPU usage. Useful when working with event-based callbacks.

Parameter Type Description
time integer time to wait in milliseconds

Obsolete Methods

passerelle.Initialize() -- obsolete >= v0.5

Previously, initializes the Saitek API. Now does nothing. Kept for compatibility purpose only.

passerelle.Release() -- obsolete >= v0.5

Previously, frees resources allocated for the Saitek API. Now does nothing. Kept for compatibility purpose only.

← Back to Contents

Window Object

The window object exposes loads of methods to control almost any opened window.

-- Find the task manager window
local win = passerelle.findWindow("TaskManagerWindow", nil);

win:capture(x, y, w, h) -- >= v0.8

Tries to capture the client area of the related window. Coordinates are in percent of the client area dimensions

Parameter Type Description
x float(0..100) x position of the capture in %
y float(0..100) y position of the capture in %
w float(0..100) width of the capture in %
h float(0..100) height of the capture in %

Upon success, returns an new object representing the window.

win:getSize() -- >= v0.8

Returns the width and height of the window client area as a multiple result set.

Return Type Description
R1 integer width of the window client area
R2 integer height of the window client area 

win:isMaximized() -- >= v0.8

Returns whether the window is maximized.

win:isMinimized() -- >= v0.8

Returns whether the window is minimized.

win:isValid() -- >= v0.8

Returns whether the window is a valid object.

win:maximize() -- >= v0.8

Maximizes the window if possible.

win:minimize() -- >= v0.8

Minimizes the window if possible.

win:restore() -- >= v0.8

Restores the window to its previous state if possible.

win:setPosition(x, y) -- >= v0.8

Sets the window position if possible.

Parameter Type Description
x integer horizontal position of the window
y integer vertical position of the window 

win:setSize(width, height) -- >= v0.8

Sets the client area size of the window if possible.

Parameter Type Description
width integer width position of the window client area
height integer height position of the window client area

If the window menu is very long, it may be displayed on multiple lines when reducing the size of the window. You may have to call this function twice to properly size the window in height.

Bitmap Object

The bitmap object is internally used to handle window capture and can be exported to be used in a GD2 context.

-- Capture the task manager window
local bitmap = win.capture(0, 0, 100, 100);

bitmap:getSize() -- >= v0.8

Returns the width and height of the bitmap as a multiple result set.

Return Type Description
R1 integer width of the bitmap
R2 integer height of the bitmap 

bitmap:gd2Str() -- >= v0.8

Returns an image in the gd2 format as a Lua string using the GD2_FMT_RAW format.

Return Type Description
R1 string image data in gd2 format
Clone this wiki locally