Home

XpressNET library Wiki

This wiki describes API is implemented by XpressNET library via public functions. This allows XpressNET library to be used as .dll or .so dynamically. This feature is used by hJOPserver.

This file describes XN library API, however, this API is designed to be used with any system supporting locomotive control (e.g. LocoNET). This is generalized by name trakce.

Errors

TRK_ALREADY_OPENNED = 2001;
TRK_CANNOT_OPEN_PORT = 2002;
TRK_NOT_OPENED = 2011;
TRK_UNSUPPORTED_API_VERSION = 4000;

API functions

enum class LogLevel {
	None = 0,
	Error = 1,
	Warning = 2,
	Info = 3,
	Commands = 4,
	RawData = 5,
	Debug = 6,
};

enum class TrkStatus {
	Unknown,
	Off,
	On,
	Programming,
};

using CommandCallbackFunc = void(*)(void *sender, void *data);

struct CommandCallback {
	CommandCallbackFunc const func;
	void *const data;
};

struct LocoInfo {
	uint16_t addr;
	bool direction;
	uint8_t speed;
	uint8_t maxSpeed;
	uint32_t functions;
};

using TrkAcquiredCallback = void(*)(const void *sender, LocoInfo);

using TrkStdNotifyEv = void(*)(const void *sender, void *data);
using TrkStatusChangedEv = void(*)(const void *sender, void *data, int trkStatus);
using TrkLogEv = void(*)(const void *sender, void *data, int logLevel, const char *msg);
using TrkLocoEv = void(*)(const void *sender, void *data, uint16_t addr);

using Cb = CommandCallback;

Library API

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

Locomotive control

TrkStatus trackStatus()

void setTrackStatus(TrkStatus, Cb ok, Cb err)

void emergencyStop(Cb ok, Cb err)

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

void locoSetSpeed(uint16_t addr, int speed, int 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 bindBefeoreOpen(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