Home

XpressNET dynamic-library API

This wiki describes API served by XpressNET dynamic-linked library. This API is used e.g. by hJOPserver.

This file describes XpressNET library API, however, the API is not for XpressNET library only. It is (hopefully) designed general enough to be used with any system supporting locomotive control (e.g. LocoNET).

Every char16_t* is a pointer to null-terminated UTF-16 string. All strings are in UTF-16.

API error codes

API types

API functions

ok and err contain references to callback functions. This library guarantees exactly 1 of the callbacks to be always called. Functions taking err as an argument never return value. When error happens in a time of calling, err event in called.

All functions never raise any exceptions.

Version

API version is unsigned int with LSB meaning the major version and second LSB meaning minor version. The rest of bytes is 0.

Library may support multiple version of API and caller may support multiple version of API too. It is caller's responsibility to choose which version of API to use. Caller determines which versions of API library supports by calling apiSupportsVersion functions. When it chooses API version, it should call apiSetVersion so the library knows the intended version of API too. These functions should be the first functions caller calls in the library.

bool apiSupportsVersion(uint version)

• Asks library if it supports API version version.

int apiSetVersion(uint version)

• Sets the API version.
• Should be called at least once at the beginning.
• Returns 0 on success.
• Returns TRK_UNSUPPORTED_API_VERSION when tried to set unsupported API version.

uint features()

• Returns bitmask of features that library supports.
• Current list of features: empty.

Configuration files

int loadConfig(char16_t *filename)

• Loads library configuration from file filename.
• This function could only be called when device is closed.
• Returns 0 by default.
• Returns TRK_FILE_CANNOT_ACCESS when cannot access configuration file.
• Returns TRK_FILE_DEVICE_OPENED when trying to load configuration with connected command station.
• Old configuration is kept if cannot access file.
• Filename filename is used for future saving of config.
• Caller is recommended to call this function right after API version determination.
• On start, library can load default config from from its working path, however in most cases there would be no config file. The responsibility for loading config file at startup is mainly on caller.

int saveConfig(char16_t *filename)

• Saves current library configuration to file filename
• Returns 0 by default.
• Returns TRK_FILE_CANNOT_ACCESS when cannot save configuration file.
• This function could be called at any time.

Connect/disconnect

int connect()

• Connects to XpressNET.
• Interface name is the responsibility of library (it stores it & allows user to change it).
• Calls beforeOpen and afterOpen events.
• Returns 0 by default.
• Returns TRK_ALREADY_OPENNED when device is already opened.
• Returns TRK_CANNOT_OPEN_PORT whet device open was unsuccessful.

int disconnect()

• Disconnects from XpressNET.
• Calls beforeClose and afterClose events.
• afterClose event is guranteed to be called (we always manage to close the device somehow).
• Returns 0 by default.
• Returns TRK_NOT_OPENED when device not opened.

bool connected()

• Returns if library is connected to the command station (COM port opened),

Track status

unsigned int trackStatus()

void setTrackStatus(unsigned int trkStatus, Cb ok, Cb err)

Locomotive control

void emergencyStop(Cb ok, Cb err)

void locoEmergencyStop(uint16_t addr, Cb ok, Cb err)

void locoSetSpeed(uint16_t addr, int speed, bool dir, Cb ok, Cb err)

void locoSetFunc(uint16_t addr, uint32_t funcMask, uint32_t funcState, Cb ok, Cb err)

Locomotive acquire/release

void locoAcquire(uint16_t addr, TrkAcquiredCallback, Cb err)

void locoRelease(uint16_t addr, Cb ok)

POM

void pomWriteCv(uint16_t addr, uint16_t cv, uint8_t value, Cb ok, Cb err)

Event binders

void bindBeforeOpen(TrkStdNotifyEv)

void bindAfterOpen(TrkStdNotifyEv)

void bindBeforeClose(TrkStdNotifyEv)

void bindAfterClose(TrkStdNotifyEv)

void bindOnTrackStatusChange(TrkStatusChangedEv)

void bindOnLog(TrkLogEv)

void bindOnLocoStolen(TrkLocoEv)

void bindOnOpenError(TrkMsgEv)

• OnOpenError event is called when there was a problem opening the device.
• After the OnOpenError is called, AfterClose is always called.

GUI

void showConfigDialog()

Changelog

v1.0

• Initial version

v1.1

• Add bindOnOpenError function & OnOpenError event.