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).

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.

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)

GUI

void showConfigDialog()

Changelog

v1.0

• Initial version