Version: doc 1.0.2 / NanoLib 1.1.2

9

6 Classes / functions reference

6 Classes / functions reference

Find here a list of NanoLib’s user interface classes and their member functions. The typical description of a function includes a short introduction, the function definition and a parameter / return list:

ExampleFunction () Tells you briefly what the function does.
Parameters param_a param_b
Returns ResultVoid

Additional comment if needed. Additional comment if needed.

6.1 NanoLibAccessor

Interface class used as entry point to the NanoLib. A typical workflow looks like this:
1. Start by scanning for hardware with NanoLibAccessor.listAvailableBusHardware (). 2. Set the communication settings with BusHardwareOptions (). 3. Open the hardware connection with NanoLibAccessor.openBusHardwareWithProtocol (). 4. Scan the bus for connected devices with NanoLibAccessor.scanDevices (). 5. Add a device with NanoLibAccessor.addDevice (). 6. Connect to the device with NanoLibAccessor.connectDevice (). 7. After finishing the operation, disconnect the device with NanoLibAccessor.disconnectDevice (). 8. Remove the device with NanoLibAccessor.removeDevice (). 9. Close the hardware connection with NanoLibAccessor.closeBusHardware ().
NanoLibAccessor has the following public member functions:

listAvailableBusHardware () Use this function to list available fieldbus hardware.
ResultBusHwIds listAvailableBusHardware ()

Returns ResultBusHwIds

Delivers a fieldbus ID array.

openBusHardwareWithProtocol () Use this function to connect bus hardware.
ResultVoid openBusHardwareWithProtocol (BusHardwareId busHwId, BusHardwareOptions busHwOpt)

Parameters busHwId busHwOpt
Returns ResultVoid

Specifies the fieldbus to open. Specifies fieldbus opening options. Confirms that a void function has run.

isBusHardwareOpen () Use this function to check if your fieldbus hardware connection is open.
boolean isBusHardwareOpen (BusHardwareId busHardwareId)

Parameters BusHardwareId Returns true
false

Specifies each fieldbus to open. Hardware is open. Hardware is closed.

Version: doc 1.0.2 / NanoLib 1.1.2

10

6 Classes / functions reference

getProtocolSpecificAccessor () Use this function to get the protocol-specific accessor object.
ResultVoid getProtocolSpecificAccessor (BusHardwareId busHwId)

Parameters busHwId Returns ResultVoid

Specifies the fieldbus to get the accessor for. Confirms that a void function has run.

getProfinetDCP () Use this function to return a reference to Profinet DCP interface.
ProfinetDCP getProfinetDCP ()

Returns ProfinetDCP

getSamplerInterface () Use this function to get a reference to the sampler interface.
SamplerInterface getSamplerInterface ()

Returns SamplerInterface

Refers to the sampler interface class.

setBusState () Use this function to set the bus-protocol-specific state.
ResultVoid setBusState (BusHardwareId busHwId, String state)

Parameters busHwId state
Returns ResultVoid

Specifies the fieldbus to open. Assigns a bus-specific state as a string value. Confirms that a void function has run.

scanDevices () Use this function to scan for devices in the network.
ResultDeviceIds scanDevices (BusHardwareId busHwId, NlcScanBusCallback callback)

Parameters busHwId callback
Returns ResultDeviceIds IOError

Specifies the fieldbus to scan. NlcScanBusCallback progress tracer. Delivers a device ID array. Informs that a device is not found.

addDevice () Use this function to add a bus device described by deviceId to NanoLib’s internal device list, and to return deviceHandle for it.
ResultDeviceHandle addDevice (DeviceId deviceId)

Parameters deviceId Returns ResultDeviceHandle

Specifies the device to add to the list. Delivers a device handle.

Version: doc 1.0.2 / NanoLib 1.1.2

11

6 Classes / functions reference

connectDevice () Use this function to connect a device by deviceHandle.
ResultVoid connectDevice (DeviceHandle deviceHandle)

Parameters deviceHandle Returns ResultVoid
IOError

Specifies what bus device NanoLib connects to. Confirms that a void function has run. Informs that a device is not found.

getDeviceName () Use this function to get a device’s name by deviceHandle.
ResultString getDeviceName (DeviceHandle deviceHandle)

Parameters deviceHandle Returns ResultString

Specifies what bus device NanoLib gets the name for. Delivers device names as a string.

getDeviceProductCode () Use this function to get a device’s product code by deviceHandle.
ResultInt getDeviceProductCode (DeviceHandle deviceHandle)

Parameters deviceHandle Returns ResultInt

Specifies what bus device NanoLib gets the product code for. Delivers product codes as an integer.

getDeviceVendorId () Use this function to get the device vendor ID by deviceHandle.
ResultInt getDeviceVendorId (DeviceHandle deviceHandle)

Parameters deviceHandle Returns ResultInt
ResourceUnavailable

Specifies what bus device NanoLib gets the vendor ID for. Delivers vendor ID’s as an integer. Informs that no data is found.

getDeviceId () Use this function to get a specific device’s ID from the NanoLib internal list.
ResultDeviceId getDeviceId (DeviceHandle deviceHandle)

Parameters deviceHandle Returns ResultDeviceId

Specifies what bus device NanoLib gets the device ID for. Delivers a device ID.

getDeviceIds () Use this function to get all devices’ ID from the NanoLib internal list.
ResultDeviceIds getDeviceIds ()

Returns ResultDeviceIds

Delivers a device ID list.

Version: doc 1.0.2 / NanoLib 1.1.2

12

6 Classes / functions reference

getDeviceUid () Use this function to get a device’s unique ID (96 bit / 12 bytes) by deviceHandle.
ResultArrayByte getDeviceUid (DeviceHandle deviceHandle)

Parameters deviceHandle Returns ResultArrayByte
ResourceUnavailable

Specifies what bus device NanoLib gets the unique ID for. Delivers unique ID’s as a byte array. Informs that no data is found.

getDeviceSerialNumber () Use this function to get a device’s serial number by deviceHandle.
ResultString getDeviceSerialNumber (DeviceHandle deviceHandle)

Parameters deviceHandle Returns ResultString
ResourceUnavailable

Specifies what bus device NanoLib gets the serial number for. Delivers serial numbers as a string. Informs that no data is found.

getDeviceHardwareGroup () Use this function to get a bus device’s hardware group by deviceHandle.
ResultInt getDeviceHardwareGroup (DeviceHandle deviceHandle)

Parameters deviceHandle Returns ResultInt

Specifies what bus device NanoLib gets the hardware group for.
Delivers hardware groups as an integer.

getDeviceHardwareVersion () Use this function to get a bus device’s hardware version by deviceHandle.
ResultString getDeviceHardwareVersion (DeviceHandle deviceHandle)

Parameters deviceHandle

Returns

ResultString ResourceUnavailable

Specifies what bus device NanoLib gets the hardware version for. Delivers device names as a string. Informs that no data is found.

getDeviceFirmwareBuildId () Use this function to get a bus device’s firmware build ID by deviceHandle.
ResultString getDeviceFirmwareBuildId (DeviceHandle deviceHandle)

Parameters deviceHandle Returns ResultString

Specifies what bus device NanoLib gets the firmware build ID for.
Delivers device names as a string.

getDeviceBootloaderVersion () Use this function to get a bus device’s bootloader version by deviceHandle.
ResultInt getDeviceBootloaderVersion (DeviceHandle deviceHandle)

Version: doc 1.0.2 / NanoLib 1.1.2

13

6 Classes / functions reference

Parameters deviceHandle

Returns

ResultInt ResourceUnavailable

Specifies what bus device NanoLib gets the bootloader version for. Delivers bootloader versions as an integer. Informs that no data is found.

getDeviceBootloaderBuildId () Use this function to get a bus device’s bootloader build ID by deviceHandle.
ResultString getDeviceBootloaderBuildId (DeviceHandle deviceHandle)

Parameters deviceHandle Returns ResultString

Specifies what bus device NanoLib gets the bootloader build ID for.
Delivers device names as a string.

rebootDevice () Use this function to reboot the device by deviceHandle.
ResultVoid rebootDevice (DeviceHandle deviceHandle)

Parameters deviceHandle Returns ResultVoid

Specifies the fieldbus to reboot. Confirms that a void function has run.

getDeviceState () Use this function to get the device-protocol-specific state.
ResultString getDeviceState (DeviceHandle deviceHandle)

Parameters deviceHandle Returns ResultString

Specifies what bus device NanoLib gets the state for. Delivers device names as a string.

setDeviceState () Use this function to set the device-protocol-specific state.
ResultVoid setDeviceState (DeviceHandle deviceHandle, String state)

Parameters deviceHandle state
Returns ResultVoid

Specifies what bus device NanoLib sets the state for. Assigns a bus-specific state as a string value. Confirms that a void function has run.

getConnectionState () Use this function to get a specific device’s last known connection state by deviceHandle (= Disconnected, Connected, ConnectedBootloader)
ResultConnectionState getConnectionState (DeviceHandle deviceHandle)

Parameters deviceHandle Returns ResultConnectionState

Specifies what bus device NanoLib gets the connection state for.
Delivers a connection state (= Disconnected, Connected, ConnectedBootloader).

Version: doc 1.0.2 / NanoLib 1.1.2

14

6 Classes / functions reference

checkConnectionState () Only if the last known state was not Disconnected: Use this function to check and possibly update a specific device’s connection state by deviceHandle and by testing several mode-specific operations.
ResultConnectionState checkConnectionState (DeviceHandle deviceHandle)

Parameters deviceHandle Returns ResultConnectionState

Specifies what bus device NanoLib checks the connection state for.
Delivers a connection state (= not Disconnected).

assignObjectDictionary () Use this manual function to assign an object dictionary (OD) to deviceHandle on your own.
ResultObjectDictionary assignObjectDictionary (DeviceHandle deviceHandle, ObjectDictionary objectDictionary)

Parameters deviceHandle objectDictionary
Returns ResultObjectDictionary

Specifies what bus device NanoLib assigns the OD to. Shows the properties of an object dictionary.

autoAssignObjectDictionary ()
Use this automatism to let NanoLib assign an object dictionary (OD) to deviceHandle. On finding and loading a suitable OD, NanoLib automatically assigns it to the device. Note: If a compatible OD is already loaded in the object library, NanoLib will automatically use it without scanning the submitted directory.
ResultObjectDictionary autoAssignObjectDictionary (DeviceHandle deviceHandle, String dictionariesLocationPath)

Parameters deviceHandle

Returns

dictionariesLocationPath ResultObjectDictionary

Specifies for which bus device NanoLib shall automatically scan for suitable OD’s. Specifies the path to the OD directory. Shows the properties of an object dictionary.

getAssignedObjectDictionary () Use this function to get the object dictionary assigned to a device by deviceHandle.
ResultObjectDictionary getAssignedObjectDictionary (DeviceHandle deviceHandle)

Parameters deviceHandle Returns ResultObjectDictionary

Specifies what bus device NanoLib gets the assigned OD for. Shows the properties of an object dictionary.

getObjectDictionaryLibrary () This function returns an OdLibrary reference.
OdLibrary getObjectDictionaryLibrary ()

Returns OdLibrary&

Opens the entire OD library and its object dictionaries.

Version: doc 1.0.2 / NanoLib 1.1.2

15

6 Classes / functions reference

setLoggingLevel () Use this function to set the needed log detailing (and log file size). Default level is Info.
void setLoggingLevel (LogLevel level)

Parameters level

The following log detailings are possible:

0 = Trace 1 = Debug 2 = Info 3 = Warn 4 = Error 5 = Critical 6 = Off

Lowest level (largest log file); logs any feasible detail, plus software start / stop. Logs debug information (= interim results, content sent or received, etc.) Default level; logs informational messages. Logs problems that did occur but won’t stop the current algorithm. Logs just severe trouble that did stop the algorithm. Highest level (smallest log file); turns logging off; no further log at all. No logging at all.

setLoggingCallback () Use this function to set a logging callback pointer and log level for that callback (not for the logger itself).
void setLoggingCallback (NlcLoggingCallback callback, LogLevel level)

Parameters *callback level

Sets a callback pointer. Sets a callback’s (not logger’s) log level.

unsetLoggingCallback () Use this function to cancel a logging callback pointer.
void unsetLoggingCallback ()

readNumber () Use this function to read a numeric value from the object dictionary.
ResultInt readNumber (DeviceHandle deviceHandle, OdIndex odIndex)

Parameters deviceHandle odIndex
Returns ResultInt

Specifies what bus device NanoLib reads from. Specifies the (sub-) index to read from. Delivers an uninterpreted numeric value (can be signed, unsigned, fix16.16 bit values).

readNumberArray () Use this function to read numeric arrays from the object dictionary.
ResultArrayInt readNumberArray (DeviceHandle deviceHandle, int index)

Parameters deviceHandle index
Returns ResultArrayInt

Specifies what bus device NanoLib reads from. Array object index. Delivers an integer array.

Version: doc 1.0.2 / NanoLib 1.1.2

16

6 Classes / functions reference

readBytes () Use this function to read arbitrary bytes (domain object data) from the object dictionary.
ResultArrayByte readBytes (DeviceHandle deviceHandle, OdIndex odIndex)

Parameters deviceHandle odIndex
Returns ResultArrayByte

Specifies what bus device NanoLib reads from. Specifies the (sub-) index to read from. Delivers a byte array.

readString () Use this function to read strings from the object directory.
ResultString readString (DeviceHandle deviceHandle, OdIndex odIndex)

Parameters deviceHandle odIndex
Returns ResultString

Specifies what bus device NanoLib reads from. Specifies the (sub-) index to read from. Delivers device names as a string.

writeNumber () Use this function to write numeric values to the object directory.
ResultVoid writeNumber (DeviceHandle deviceHandle, long value, OdIndex odIndex, long bitLength)

Parameters deviceHandle value odIndex bitLength
Returns ResultVoid

Specifies what bus device NanoLib writes to. The uninterpreted value (can be signed, unsigned, fix 16.16). Specifies the (sub-) index to read from. Length in bit. Confirms that a void function has run.

writeBytes () Use this function to write arbitrary bytes (domain object data) to the object directory.
ResultVoid writeBytes (DeviceHandle deviceHandle, ByteVector data, OdIndex odIndex)

Parameters deviceHandle data odIndex
Returns ResultVoid

Specifies what bus device NanoLib writes to. Byte vector / array. Specifies the (sub-) index to read from. Confirms that a void function has run.

uploadFirmware () Use this function to update your controller firmware.
ResultVoid uploadFirmware (DeviceHandle deviceHandle, ByteVector fwData, NlcDataTransferCallback callback)

Parameters deviceHandle fwData NlcDataTransferCallback
Returns ResultVoid

Specifies what bus device NanoLib updates. Array containing firmware data. A data progress tracer. Confirms that a void function has run.

Version: doc 1.0.2 / NanoLib 1.1.2

17

6 Classes / functions reference

uploadFirmwareFromFile () Use this function to update your controller firmware by uploading its file.
ResultVoid uploadFirmwareFromFile (DeviceHandle deviceHandle, String absoluteFilePath, NlcDataTransferCallback callback)

Parameters deviceHandle absoluteFilePath NlcDataTransferCallback
Returns ResultVoid

Specifies what bus device NanoLib updates. Path to file containing firmware data (string). A data progress tracer. Confirms that a void function has run.

uploadBootloader () Use this function to update your controller bootloader.
ResultVoid uploadBootloader (DeviceHandle deviceHandle, ByteVector btData, NlcDataTransferCallback callback)

Parameters deviceHandle btData NlcDataTransferCallback
Returns ResultVoid

Specifies what bus device NanoLib updates. Array containing bootloader data. A data progress tracer. Confirms that a void function has run.

uploadBootloaderFromFile () Use this function to update your controller bootloader by uploading its file.
ResultVoid uploadBootloaderFromFile (DeviceHandle deviceHandle, String bootloaderAbsoluteFilePath, NlcDataTransferCallback callback)

Parameters deviceHandle bootloaderAbsoluteFilePath NlcDataTransferCallback
Returns ResultVoid

Specifies what bus device NanoLib updates. Path to file containing bootloader data (string). A data progress tracer. Confirms that a void function has run.

uploadBootloaderFirmware () Use this function to update your controller bootloader and firmware.
ResultVoid uploadBootloaderFirmware (DeviceHandle deviceHandle, ByteVector btData, ByteVector fwData, NlcDataTransferCallback callback)

Parameters deviceHandle btData fwData NlcDataTransferCallback
Returns ResultVoid

Specifies what bus device NanoLib updates. Array containing bootloader data. Array containing firmware data. A data progress tracer. Confirms that a void function has run.

uploadBootloaderFirmwareFromFile ()
Use this function to update your controller bootloader and firmware by uploading the files.
ResultVoid uploadBootloaderFirmwareFromFile (DeviceHandle deviceHandle, String bootloaderAbsoluteFilePath, String absoluteFilePath, NlcDataTransferCallback callback)

Version: doc 1.0.2 / NanoLib 1.1.2

18

6 Classes / functions reference

Parameters deviceHandle bootloaderAbsoluteFilePath absoluteFilePath NlcDataTransferCallback
Returns ResultVoid

Specifies what bus device NanoLib updates. Path to file containing bootloader data (string). Path to file containing firmware data (uint8_t). A data progress tracer. Confirms that a void function has run.

uploadNanoJ () Use this public function to updload the NanoJ program to your controller.
ResultVoid uploadNanoJ(DeviceHandle deviceHandle, ByteVector vmmData, NlcDataTransferCallback callback)

Parameters deviceHandle vmmData NlcDataTransferCallback
Returns ResultVoid

Specifies what bus device NanoLib uploads to. Array containing NanoJ data. A data progress tracer. Confirms that a void function has run.

uploadNanoJFromFile () Use this public function to updload the NanoJ program to your controller by uploading the file.
ResultVoid uploadNanoJFromFile (DeviceHandle deviceHandle, String absoluteFilePath, NlcDataTransferCallback callback)

Parameters deviceHandle absoluteFilePath NlcDataTransferCallback
Returns ResultVoid

Specifies what bus device NanoLib uploads to. Path to file containing NanoJ data (string). A data progress tracer. Confirms that a void function has run.

disconnectDevice () Use this function to disconnect your device by deviceHandle.
ResultVoid disconnectDevice (DeviceHandle deviceHandle)

Parameters deviceHandle Returns ResultVoid

Specifies what bus device NanoLib disconnects from. Confirms that a void function has run.

removeDevice () Use this function to remove your device from NanoLib’s internal device list.
ResultVoid removeDevice (DeviceHandle deviceHandle)

Parameters deviceHandle Returns ResultVoid

Specifies what bus device NanoLib delists. Confirms that a void function has run.

closeBusHardware () Use this function to disconnect from your fieldbus hardware.
ResultVoid closeBusHardware (BusHardwareId busHwId)

Parameters busHwId Returns ResultVoid

Specifies the fieldbus to disconnect from. Confirms that a void function has run.

Version: doc 1.0.2 / NanoLib 1.1.2

19

6 Classes / functions reference

6.2 BusHardwareId
Use this class to identify a bus hardware one-to-one or to distinguish different bus hardware from each other. This class (without setter functions to be immutable from creation on) also holds information on:
Hardware (= adapter name, network adapter etc.) Protocol to use (= Modbus TCP, CANopen etc.) Bus hardware specifier (= serial port name, MAC Friendly name
address etc.)

BusHardwareId () [1/3] Constructor that creates a new bus hardware ID object.
BusHardwareId (String busHardware, String protocol, String hardwareSpecifier, String name) dwareSpecifier, name

Parameters busHardware protocol hardwareSpecifier extraHardwareSpecifier name_

Hardware type (= ZK-USB-CAN-1 etc.). Bus communication protocol (= CANopen etc.). The specifier of a hardware (= COM3 etc.). The extra specifier of the hardware (say, USB location info). A friendly name (= AdapterName (Port) etc. ).

BusHardwareId () [2/3] Constructor that creates a new bus hardware ID object, with the option for an extra hardware speicifier.
BusHardwareId (String busHardware, String protocol, String hardwareSpecifier, String extraHardwareSpecifier, String name_)

Parameters busHardware protocol hardwareSpecifier extraHardwareSpecifier name_

Hardware type (= ZK-USB-CAN-1 etc.). Bus communication protocol (= CANopen etc.). The specifier of a hardware (= COM3 etc.). The extra specifier of the hardware (say, USB location info). A friendly name (= AdapterName (Port) etc. ).

BusHardwareId () [3/3] Constructor that copies an exisiting busHardwareId.
nlc::BusHardwareId::BusHardwareId (BusHardwareId const &)

BusHardwareId (BusHardwareId arg0)

Parameters busHardwareId

Names the bus hardware ID to copy from.

equals () Compares a new bus hardware ID to existing ones.
boolean equals (BusHardwareId other)

Parameters other Returns true
false

Another object of the same class. If both are equal in all values. If the values differ.

Version: doc 1.0.2 / NanoLib 1.1.2

20

6 Classes / functions reference
getBusHardware () Reads out the bus hardware string.
String getBusHardware () Returns string getHardwareSpecifier () Reads out the bus hardware’s specifier string (= network name etc.). String getBusHardware () Returns string getExtraHardwareSpecifier () Reads out the bus extra hardware’s specifier string (= MAC address etc.). String getExtraHardwareSpecifier () Returns string getName () Reads out the bus hardware’s friendly name. String getName () Returns string getProtocol () Reads out the bus protocol string. String getProtocol () Returns string toString () Returns the bus hardware ID as a string. String toString () Returns string
6.3 BusHardwareOptions
Find in this class, in a key-value list of strings, all options needed to open a bus hardware. BusHardwareOptions () [1/2] Constructs a new bus hardware option object.
BusHardwareOptions () Use the function addOption () to add key-value pairs.

Version: doc 1.0.2 / NanoLib 1.1.2

21

6 Classes / functions reference

BusHardwareOptions () [2/2] Constructs a new bus hardware options object with the key-value map already in place.
BusHardwareOptions (StringStringMap options)

Parameters options

A map with options for the bus hardware to operate.

addOption () Creates additional keys and values.
void addOption (String key, String value)

Parameters key value

Example: BAUD_RATE_OPTIONS_NAME, see bus_hwoptions defaults
Example: BAUD_RATE_1000K, see bus_hw_options_defaults

equals () Compares the BusHardwareOptions to existing ones.
boolean equals (BusHardwareOptions other)

Parameters other Returns true
false

Another object of the same class. If the other object has all of the exact same options. If the other object has different keys or values.

getOptions () Reads out all added key-value pairs.
StringStringMap getOptions ()

Returns string map

toString () Returns all keys / values as a string.
String toString ()

Returns string

6.4 BusHwOptionsDefault

This default configuration options class has the following public attributes:

const CanBus const Serial const RESTfulBus const EtherCATBus

canBus = CanBus () serial = Serial () restfulBus = RESTfulBus() ethercatBus = EtherCATBus()

6.5 CanBaudRate

Struct that contains CAN bus baudrates in the following public attributes:

Version: doc 1.0.2 / NanoLib 1.1.2

22

6 Classes / functions reference

string string string string string string string string string string

BAUD_RATE_1000K = “1000k” BAUD_RATE_800K = “800k” BAUD_RATE_500K = “500k” BAUD_RATE_250K = “250k” BAUD_RATE_125K = “125k” BAUD_RATE_100K = “100k” BAUD_RATE_50K = “50k” BAUD_RATE_20K = “20k” BAUD_RATE_10K = “10k” BAUD_RATE_5K = “5k”

6.6 CanBus

Default configuration options class with the following public attributes:

string const CanBaudRate const Ixxat

BAUD_RATE_OPTIONS_NAME = “can adapter baud rate” baudRate = CanBaudRate () ixxat = Ixxat ()

6.7 CanOpenNmtService

For the NMT service, this struct contains the CANopen NMT states as string values in the following public attributes:

string string string string string

START = “START” STOP = “STOP” PRE_OPERATIONAL = “PRE_OPERATIONAL” RESET = “RESET” RESET_COMMUNICATION = “RESET_COMMUNICATION”

6.8 CanOpenNmtState

This struct contains the CANopen NMT states as string values in the following public attributes:

string string string string string

STOPPED = “STOPPED” PRE_OPERATIONAL = “PRE_OPERATIONAL” OPERATIONAL = “OPERATIONAL” INITIALIZATION = “INITIALIZATION” UNKNOWN = “UNKNOWN”

6.9 EtherCATBus struct

This struct contains the EtherCAT communication configuration options in the following public attributes:

string NETWORK_FIRMWARE_STATE_OPTION_NAME Network state treated as firmware mode. Acceptable

= “Network Firmware State”

values (default = PRE_OPERATIONAL):

EtherCATState::PRE_OPERATIONAL EtherCATState::SAFE_OPERATIONAL EtherCATState::OPERATIONAL

string DEFAULT_NETWORK_FIRMWARE_STATE = “PRE_OPERATIONAL”

Version: doc 1.0.2 / NanoLib 1.1.2

23

6 Classes / functions reference

string EXCLUSIVE_LOCK_TIMEOUT_OPTION_NAME Timeout in milliseconds to acquire exclusive lock on

= “Shared Lock Timeout”

the network (default = 500 ms).

const unsigned int DEFAULT_EXCLUSIVELOCK TIMEOUT = “500”

string SHARED_LOCK_TIMEOUT_OPTION_NAME = Timeout in milliseconds to acquire shared lock on

“Shared Lock Timeout”

the network (default = 250 ms).

const unsigned int DEFAULT_SHARED_LOCK_TIMEOUT = “250”

string READ_TIMEOUT_OPTION_NAME = “Read Timeout”

Timeout in milliseconds for a read operation (default = 700 ms).

const unsigned int DEFAULT_READ_TIMEOUT = “700”

string WRITE_TIMEOUT_OPTION_NAME = “Write Timeout”

Timeout in milliseconds for a write operation (default = 200 ms).

const unsigned int DEFAULT_WRITE_TIMEOUT = “200”

string READ_WRITE_ATTEMPTS_OPTION_NAME = Maximum read or write attempts (non- zero values

“Read/Write Attempts”

only; default = 5).

const unsigned int DEFAULT_READ_WRITE_ATTEMPTS = “5”

string CHANGE_NETWORK_STATE_ATTEMPTS_OPTION_NAME = “Change Network State Attempts”

Maximum number of attempts to alter the network state (non-zero values only; default = 10).

const unsigned int DEFAULT_CHANGENETWORK STATE_ATTEMPTS = “10”

string PDO_IO_ENABLED_OPTION_NAME = “PDO IO Enables or disables PDO processing for digital in- /

Enabled”

outputs (“True” or “False” only; default = “True”).

string DEFAULT_PDO_IO_ENABLED = “True”

6.10 EtherCATState struct

This struct contains the EtherCAT slave / network states as string values in the following public attributes. Note: Default state at power on is PRE_OPERATIONAL; NanoLib can provide no reliable “OPERATIONAL” state in a non- realtime operating system:

string string string string string string

NONE = “NONE” INIT = “INIT” PRE_OPERATIONAL = “PRE_OPERATIONAL” BOOT = “BOOT” SAFE_OPERATIONAL = “SAFE_OPERATIONAL” OPERATIONAL = “OPERATIONAL”

6.11 Ixxat

This struct holds all information for the IXXAT usb-to-can in the following public attributes:

string

ADAPTER_BUS_NUMBER_OPTIONS_NAME = “ixxat adapter bus number”

const IxxatAdapterBusNumber adapterBusNumber = IxxatAdapterBusNumber ()

6.12 IxxatAdapterBusNumber

This struct holds the bus number for the IXXAT usb-to-can in the following public attributes:

string

BUS_NUMBER_0_DEFAULT = “0”

Version: doc 1.0.2 / NanoLib 1.1.2

24

6 Classes / functions reference

string string string

BUS_NUMBER_1 = “1” BUS_NUMBER_2 = “2” BUS_NUMBER_3 = “3”

6.13 DeviceHandle
This class represents a handle for controlling a device on a bus and has the following public member functions.

DeviceHandle () DeviceHandle ()

equals () Compares itself to a given device handle.
boolean equals (DeviceHandle other)

toString () Returns a string representation of the device handle.
String toString ()

6.14 DeviceId
Use this class (not immutable from creation on) to identify and distinguish devices on a bus:

Hardware adapter identifier

Device identifier

Description

The meaning of device ID / description values depends on the bus. For example, a CAN bus may use the integer ID.

DeviceId () [1/3] Constructs a new device ID object.
DeviceId (BusHardwareId busHardwareId, long deviceId, String description_)

Parameters busHardwareId deviceId description_

Identifier of the bus. An index; subject to bus (= CANopen node ID etc.). A description (may be empty); subject to bus.

DeviceId () [2/3] Constructs a new device ID object with extended ID options.
DeviceId (BusHardwareId busHardwareId, long deviceId, String description, ByteVector extraId, String extraStringId_)

Parameters busHardwareId deviceId description extraId

Identifier of the bus. An index; subject to bus (= CANopen node ID etc.). A description (may be empty); subject to bus. An additional ID (may be empty); meaning depends on bus.

Version: doc 1.0.2 / NanoLib 1.1.2

25

6 Classes / functions reference

extraStringId_

Additional string ID (may be empty); meaning depends on bus.

DeviceId () [3/3] Constructs a copy of a device ID object.
DeviceId (DeviceId arg0)

Parameters deviceId_

Device ID to copy from.

equals () Compares new to existing objects.
boolean equals (DeviceId other)

Returns boolean

getBusHardwareId () Reads out the bus hardware ID.
BusHardwareId getBusHardwareId ()

Returns BusHardwareId

getDescription () Reads out the device description (maybe unused).
String getDescription ()

Returns string

getDeviceId () Reads out the device ID (maybe unused).
long getDeviceId ()

Returns unsigned int

toString () Returns the object as a string.
String toString ()

Returns string

getExtraId () Reads out the extra ID of the device (may be unused).
ByteVector getExtraId ()

Returns vector extraId_

A vector of the additional extra ID’s (may be empty); meaning depends on the bus.

Version: doc 1.0.2 / NanoLib 1.1.2

26

6 Classes / functions reference

getExtraStringId () Reads out the extra string ID of the device (may be unused).
String getExtraStringId ()

Returns string

The additional string ID (may be empty); meaning depends on the bus.

6.15 LogLevelConverter

This class returns your log level as a string. static String toString (LogLevel logLevel)

6.16 ObjectDictionary
This class represents an object dictionary of a controller and has the following public member functions: getDeviceHandle ()
ResultDeviceHandle getDeviceHandle () Returns ResultDeviceHandle getObject () ResultObjectSubEntry getObject (OdIndex odIndex) Returns ResultObjectSubEntry

getObjectEntry () ResultObjectEntry getObjectEntry (int index)

Returns ResultObjectEntry

Informs on an object’s properties.

getXmlFileName () getXmlFileName (self)

ResultString getXmlFileName ()

Returns ResultString

Returns the XML file name as a string.

readNumber () ResultInt readNumber (OdIndex odIndex) Returns ResultInt
readNumberArray () ResultArrayInt readNumberArray (int index)

Version: doc 1.0.2 / NanoLib 1.1.2

27

6 Classes / functions reference
Returns ResultArrayInt readString ()
ResultString readString (OdIndex odIndex) Returns ResultString readBytes () ResultArrayByte readBytes (OdIndex odIndex) Returns ResultArrayByte writeNumber () ResultVoid writeNumber (OdIndex odIndex, long value) Returns ResultVoid writeBytes () ResultVoid writeBytes (OdIndex odIndex, ByteVector data) Returns ResultVoid Related Links OdIndex
6.17 ObjectEntry
This class represents an object entry of the object dictionary and has the following public member functions: getName () Reads out the name of the object as a string.
String getName ()
getPrivate () Checks if the object is private.
boolean getPrivate ()
getIndex () Reads out the address of the object index.
int getIndex ()
getDataType () Reads out the data type of the object.
ObjectEntryDataType getDataType ()

Version: doc 1.0.2 / NanoLib 1.1.2

28

6 Classes / functions reference

getObjectCode () Reads out the object code:

Null Deftype Defstruct Var Array Record

0x00 0x05 0x06 0x07 0x08 0x09

ObjectCode getObjectCode ()

getObjectSaveable () Checks if the object is saveable and it’s category (see product manual for more details): APPLICATION, COMMUNICATION, DRIVE, MISC_CONFIG, MODBUS_RTU, NO, TUNING, CUSTOMER, ETHERNET, CANOPEN, VERIFY1020, UNKNOWN_SAVEABLE_TYPE
ObjectSaveable getObjectSaveable ()

getMaxSubIndex () Reads out the number of subindices supported by this object.
short getMaxSubIndex()

getSubEntry () ObjectSubEntry getSubEntry (short subIndex)
See also ObjectSubEntry.
6.18 ObjectSubEntry
This class represents an object sub-entry (subindex) of the object dictionary and has the following public member functions:
getName () Reads out the name of the object as a string.
String getName ()

getSubIndex () Reads out the address of the subindex.
short getSubIndex ()

getDataType () Reads out the data type of the object.
ObjectEntryDataType getDataType ()

Version: doc 1.0.2 / NanoLib 1.1.2

29

6 Classes / functions reference

getSdoAccess () Checks if the subindex is accessible via SDO:

ReadOnly

1

WriteOnly

2

ReadWrite

3

NoAccess

0

ObjectSdoAccessAttribute getSdoAccess ()

getPdoAccess () Checks if the subindex is accessible/mappable via PDO:

Tx

1

Rx

2

TxRx

3

No

0

ObjectPdoAccessAttribute getPdoAccess ()

getBitLength () Checks the subindex length.
long getBitLength ()

getDefaultValueAsNumeric () Reads out the default value of the subindex for numeric data types.
ResultInt getDefaultValueAsNumeric (String key)

getDefaultValueAsString () Reads out the default value of the subindex for string data types.
ResultString getDefaultValueAsString (String key)

getDefaultValues () Reads out the default values of the subindex.
StringStringMap getDefaultValues ()

readNumber () Reads out the numeric actual value of the subindex.
ResultInt readNumber ()

Version: doc 1.0.2 / NanoLib 1.1.2

30

6 Classes / functions reference

readString () Reads out the string actual value of the subindex.
ResultString readString ()

readBytes () Reads out the actual value of the subindex in bytes.
ResultArrayByte readBytes ()

writeNumber () Writes a numeric value in the subindex.
ResultVoid writeNumber (long value)

writeBytes () Writes a value in the subindex in bytes.
ResultVoid writeBytes (ByteVector data)

6.19 OdIndex
Use this class (immutable from creation on) to wrap and locate object directory indices / sub-indices. A device’s OD has up to 65535 (0xFFFF) rows and 255 (0xFF) columns; with gaps between the discontinuous rows. See the CANopen standard and your product manual for more detail.
OdIndex () Constructs a new OdIndex object.
OdIndex()

Parameters index subindex

From 0 to 65535 (0xFFFF) incl. From 0 to 255 (0xFF) incl.

getIndex () Reads out the index (from 0x0000 to 0xFFFF).
int getIndex()

getSubindex () Reads out the sub-index (from 0x00 to 0xFF)
short getSubIndex()

toString () Returns the index and subindex as a string. The string default 0xIIII:0xSS reads as follows:

Version: doc 1.0.2 / NanoLib 1.1.2

31

6 Classes / functions reference

I = index from 0x0000 to 0xFFFF

S = sub-index from 0x00 to 0xFF

std::string nlc::OdIndex::toString () const

String toString ()

Returns 0xIIII:0xSS

Default string representation

6.20 OdIndexVector

Helping class that creates a vector of OdIndex objects, to build an object dictionary.

6.21 OdLibrary

Use this programming interface to create instances of the ObjectDictionary class from XML. By assignObjectDictionary, you can then bind each instance to a specific device due to a uniquely created identifier. ObjectDictionary instances thus created are stored in the OdLibrary object to be accessed by index. The ODLibrary class loads ObjectDictionary items from file or array, stores them, and has the following public member functions:

getObjectDictionaryCount () long getObjectDictionaryCount ()

getObjectDictionary () ResultObjectDictionary getObjectDictionary (long odIndex)
Returns ResultObjectDictionary
addObjectDictionaryFromFile () ResultObjectDictionary addObjectDictionaryFromFile (String absoluteXmlFilePath)
Returns ResultObjectDictionary
addObjectDictionary () virtual ResultObjectDictionary addObjectDictionary (std::vector const & odXmlData, const std::string &xmlFilePath = std::string ())
ResultObjectDictionary addObjectDictionary (ByteVector odXmlData, String xmlFilePath)
Returns ResultObjectDictionary
6.22 OdTypesHelper

uintToObjectCode () Converts unsigned integers to object code:

Null

0x00

Version: doc 1.0.2 / NanoLib 1.1.2

32

6 Classes / functions reference

Deftype Defstruct Var Array Record

0x05 0x06 0x07 0x08 0x09

static ObjectCode uintToObjectCode (long objectCode)

isNumericDataType () Informs if a data type is numeric or not.
static boolean isNumericDataType (ObjectEntryDataType dataType)

isDefstructIndex () Informs if an object is a definition structure index or not.
static boolean isDefstructIndex (int typeNum)

isDeftypeIndex () Informs if an object is a definition type index or not.
static boolean isDeftypeIndex (int typeNum)

isComplexDataType () Informs if a data type is complex or not.
static boolean isComplexDataType (ObjectEntryDataType dataType)

uintToObjectEntryDataType () Converts unsigned integers to OD data type.
static ObjectEntryDataType uintToObjectEntryDataType

objectEntryDataTypeToString () Converts OD data type to string.
static String objectEntryDataTypeToString (ObjectEntryDataType odDataType)

stringToObjectEntryDatatype () Converts string to OD data type if possible. Otherwise, returns UNKNOWN_DATATYPE.
static ObjectEntryDataType stringToObjectEntryDatatype (String dataTypeString)

objectEntryDataTypeBitLength () Informs on bit length of an object entry data type.
static long objectEntryDataTypeBitLength (ObjectEntryDataType dataType)

Version: doc 1.0.2 / NanoLib 1.1.2

33

6 Classes / functions reference

6.23 RESTfulBus struct

This struct contains the communication configuration options for the RESTful interface (over Ethernet). It contains the following public attributes:

const std::string const unsigned long const std::string const unsigned long const std::string const unsigned long

CONNECT_TIMEOUT_OPTION_NAME = “RESTful Connect Timeout” DEFAULT_CONNECT_TIMEOUT = 200 REQUEST_TIMEOUT_OPTION_NAME = “RESTful Request Timeout” DEFAULT_REQUEST_TIMEOUT = 200 RESPONSE_TIMEOUT_OPTION_NAME = “RESTful Response Timeout” DEFAULT_RESPONSE_TIMEOUT = 750

6.24 ProfinetDCP
Under Linux, the calling application needs CAP_NET_ADMIN and CAP_NET_RAW capabilities. To enable: sudo setcap ‘cap_net_admin,cap_net_raw+eip’ ./executable. In Windows, the ProfinetDCP interface uses WinPcap (tested with version 4.1.3) or Npcap (tested with versions 1.60 and 1.30). It thus searches the dynamically loaded wpcap.dll library in the following order (Note: no current Win10Pcap support):
1. Nanolib.dll directory 2. Windows system directory SystemRoot%System32 3. Npcap installation directory SystemRoot%System32Npcap 4. Environment path
This class represents a Profinet DCP interface and has the following public member functions:

getScanTimeout () Informs on a device scan timeout (default = 2000 ms).
long getScanTimeout ()

setScanTimeout () Sets a device scan timeout (default = 2000 ms).
void setScanTimeout (long timeoutMsec)

getResponseTimeout () Informs on a device response timeout for setup, reset and blink operations (default = 1000 ms).
long getResponseTimeout ()

setResponseTimeout () Informs on a device response timeout for setup, reset and blink operations (default = 1000 ms).
void setResponseTimeout (long timeoutMsec)

isServiceAvailable ()
Use this function to check Profinet DCP service availability.
Network adapter validity / availability Windows: WinPcap / Npcap availability

Version: doc 1.0.2 / NanoLib 1.1.2

34

6 Classes / functions reference

Linux: CAP_NET_ADMIN / CAP_NET_RAW capabilities ResultVoid isServiceAvailable (BusHardwareId busHardwareId)

Parameters BusHardwareId Returns true
false

Hardware ID of Profinet DCP service to check. Service is available. Service is unavailable.

scanProfinetDevices () Use this function to scan the hardware bus for the presence of Profinet devices.
ResultProfinetDevices scanProfinetDevices (BusHardwareId busHardwareId)

Parameters BusHardwareId Returns ResultProfinetDevices

Specifies each fieldbus to open. Hardware is open.

setupProfinetDevice () Establishes the following device settings:

Device name

IP address

Network mask

Default gateway

ResultVoid setupProfinetDevice (BusHardwareId busHardwareId, ProfinetDevice profinetDevice, boolean savePermanent)

resetProfinetDevice () Stops the device and resets it to factory defaults.
ResultVoid resetProfinetDevice (BusHardwareId busHardwareId, ProfinetDevice profinetDevice)

blinkProfinetDevice () Commands the Profinet device to start blinking its Profinet LED.
ResultVoid blinkProfinetDevice (BusHardwareId busHardwareId, ProfinetDevice profinetDevice)

validateProfinetDeviceIp () Use this function to check device’s IP address.
ResultVoid validateProfinetDeviceIp (BusHardwareId busHardwareId, ProfinetDevice profinetDevice)

Parameters BusHardwareId ProfinetDevice
Returns ResultVoid

Specifies the hardware ID to check. Specifies the Profinet device to validate.

6.25 ProfinetDevice struct

The Profinet device data have the following public attributes:

std::string

deviceName

Version: doc 1.0.2 / NanoLib 1.1.2

35

6 Classes / functions reference

std::string std::array< uint8_t, 6 > uint32_t uint32_t uint32_t

deviceVendor macAddress ipAddress netMask defaultGateway

The MAC address is provided as array in format macAddress = {xx, xx, xx, xx, xx, xx}; whereas IP address, network mask and gateway are all interpreted as big endian hex numbers, such as:

IP address: 192.168.0.2 Network mask: 255.255.0.0 Gateway: 192.168.0.1

0xC0A80002 0xFFFF0000 0xC0A80001

6.26 Result classes

Use the “optional” return values of these classes to check if a function call had success or not, and also locate the fail reasons. On success, the hasError () function returns false. By getResult (), you can read out the result value as per type (ResultInt etc.). If a call fails, you read out the reason by getError ().

Protected attributes

string NlcErrorCode uint32_t

errorString errorCode exErrorCode

Also, this class has the following public member functions:

hasError () Reads out a function call’s success.
boolean hasError ()

Returns

true false

Failed call. Use getError () to read out the value. Sucessful call. Use getResult () to read out the value.

getError () Reads out the reason if a function call fails.
String getError ()

Returns const string

getErrorCode () Read the NlcErrorCode.
NlcErrorCode getErrorCode ()

getExErrorCode () uint32_t getExErrorCode () const long getExErrorCode ()

Version: doc 1.0.2 / NanoLib 1.1.2

36

6 Classes / functions reference
6.26.1 ResultVoid
NanoLib sends you an instance of this class if the function returns void. The class inherits the public functions and protected attributes from the result class and has the following public member functions:
ResultVoid () The following functions aid in defining the exact void result:
ResultVoid (String errorString)
ResultVoid (NlcErrorCode errCode, String errorString)
ResultVoid (NlcErrorCode errCode, long exErrCode, String errorString)
ResultVoid (Result result)
6.26.2 ResultInt
NanoLib sends you an instance of this class if the function returns an integer. The class inherits the public functions / protected attributes from the result class and has the following public member functions:
getResult () Returns the integer result if a function call had success.
long getResult ()
Returns long
ResultInt () The following functions aid in defining the exact integer result:
ResultInt (long result)
ResultInt (String errorString)
ResultInt (NlcErrorCode errCode, String errorString)
ResultInt (NlcErrorCode errCode, long exErrCode, String errorString_)
ResultInt (Result result)
6.26.3 ResultString
NanoLib sends you an instance of this class if the function returns a string. The class inherits the public functions / protected attributes from the result class and has the following public member functions:
getResult () Reads out the string result if a function call had success.
String getResult ()
Returns const string

Version: doc 1.0.2 / NanoLib 1.1.2

37

6 Classes / functions reference
ResultString () The following functions aid in defining the exact string result:
ResultString (String message, boolean hasError)
ResultString (NlcErrorCode errCode, String errorString)
ResultString (NlcErrorCode errCode, long exErrCode, String errorString_)
ResultString (Result result)
6.26.4 ResultArrayByte
NanoLib sends you an instance of this class if the function returns a byte array. The class inherits the public functions / protected attributes from the result class and has the following public member functions: getResult () Reads out the byte vector if a function call had success.
ByteVector getResult () Returns const vector
ResultArrayByte () The following functions aid in defining the exact byte array result:
ResultArrayByte (ByteVector result)
ResultArrayByte (String errorString)
ResultArrayByte (NlcErrorCode errCode, String errorString)
ResultArrayByte (NlcErrorCode errCode, long exErrCode, String errorString)
ResultArrayByte (Result result)
6.26.5 ResultArrayInt
NanoLib sends you an instance of this class if the function returns an integer array. The class inherits the public functions / protected attributes from the result class and has the following public member functions: getResult () Reads out the integer vector if a function call had success.
IntVector getResult () Returns const vector

Version: doc 1.0.2 / NanoLib 1.1.2

38

6 Classes / functions reference
ResultArrayInt () The following functions aid in defining the exact integer array result:
ResultArrayInt (IntVector result)
ResultArrayInt (String errorString)
ResultArrayInt (NlcErrorCode errCode, String errorString)
ResultArrayInt (NlcErrorCode errCode, long exErrCode, String errorString)
ResultArrayInt (Result result)
6.26.6 ResultBusHwIds
NanoLib sends you an instance of this class if the function returns a bus hardware ID array. The class inherits the public functions / protected attributes from the result class and has the following public member functions: getResult () Reads out the bus-hardware-ID vector if a function call had success.
BusHWIdVector getResult ()
Parameters const vector
ResultBusHwIds () The following functions aid in defining the exact bus- hardware-ID-array result:
ResultBusHwIds (BusHWIdVector result)
ResultBusHwIds (String errorString)
ResultBusHwIds (NlcErrorCode errCode, String errorString)
ResultBusHwIds (NlcErrorCode errCode, long exErrCode, String errorString)
ResultBusHwIds (Result result)
6.26.7 ResultDeviceId
NanoLib sends you an instance of this class if the function returns a device ID. The class inherits the public functions / protected attributes from the result class and has the following public member functions: getResult () Reads out the device ID vector if a function call had success.
DeviceId getResult ()
Returns const vector

Version: doc 1.0.2 / NanoLib 1.1.2

39

6 Classes / functions reference
ResultDeviceId () The following functions aid in defining the exact device ID result:
ResultDeviceId (DeviceId result)
ResultDeviceId (String errorString)
ResultDeviceId (NlcErrorCode errCode, String errorString)
ResultDeviceId (NlcErrorCode errCode, long exErrCode, String errorString)
ResultDeviceId (Result result)
6.26.8 ResultDeviceIds
NanoLib sends you an instance of this class if the function returns a device ID array. The class inherits the public functions / protected attributes from the result class and has the following public member functions: getResult () Returns the device ID vector if a function call had success.
DeviceIdVector getResult ()
Returns const vector
ResultDeviceIds () The following functions aid in defining the exact device- ID-array result:
ResultDeviceIds (DeviceIdVector result)
ResultDeviceIds (String errorString)
ResultDeviceIds (NlcErrorCode errCode, String errorString)
ResultDeviceIds (NlcErrorCode errCode, long exErrCode, String errorString)
ResultDeviceIds (Result result)
6.26.9 ResultDeviceHandle
NanoLib sends you an instance of this class if the function returns the value of a device handle. The class inherits the public functions / protected attributes from the result class and has the following public member functions: getResult () Reads out the device handle if a function call had success.
DeviceHandle getResult ()
Returns DeviceHandle

Version: doc 1.0.2 / NanoLib 1.1.2

40

6 Classes / functions reference

ResultDeviceHandle () The following functions aid in defining the exact device handle result:
ResultDeviceHandle (DeviceHandle result_)

ResultDeviceHandle (String errorString_)

ResultDeviceHandle (NlcErrorCode errCode, String errorString_)

ResultDeviceHandle (NlcErrorCode errCode, long exErrCode, String errorString_)

ResultDeviceHandle (Result result)

6.26.10 ResultObjectDictionary
NanoLib sends you an instance of this class if the function returns the content of an object dictionary. The class inherits the public functions / protected attributes from the result class and has the following public member functions:

getResult () Reads out the device ID vector if a function call had success.
ObjectDictionary getResult ()

Returns

const vector

ResultObjectDictionary () The following functions aid in defining the exact object dictionary result:
ResultObjectDictionary (ObjectDictionary result_)

ResultObjectDictionary (String errorString_)

ResultObjectDictionary (NlcErrorCode errCode, String errorString_)

ResultObjectDictionary (NlcErrorCode errCode, long exErrCode, String errorString_)

ResultObjectDictionary (Result result)

6.26.11 ResultConnectionState
NanoLib sends you an instance of this class if the function returns a device- connection-state info. The class inherits the public functions / protected attributes from the result class and has the following public member functions:
getResult () Reads out the device handle if a function call had success.
DeviceConnectionStateInfo getResult ()
Returns DeviceConnectionStateInfo Connected / Disconnected / ConnectedBootloader

Version: doc 1.0.2 / NanoLib 1.1.2

41

6 Classes / functions reference
ResultConnectionState () The following functions aid in defining the exact connection state result:
ResultConnectionState (DeviceConnectionStateInfo result)
ResultConnectionState (String errorString)
ResultConnectionState (NlcErrorCode errCode, String errorString)
ResultConnectionState (NlcErrorCode errCode, long exErrCode, String errorString)
ResultConnectionState (Result result)
6.26.12 ResultObjectEntry
NanoLib sends you an instance of this class if the function returns an object entry. The class inherits the public functions / protected attributes from the result class and has the following public member functions: getResult () Returns the device ID vector if a function call had success.
ObjectEntry getResult ()
Returns const ObjectEntry
ResultObjectEntry () The following functions aid in defining the exact object entry result:
ResultObjectEntry (ObjectEntry result)
ResultObjectEntry (String errorString)
ResultObjectEntry (NlcErrorCode errCode, String errorString)
ResultObjectEntry (NlcErrorCode errCode, long exErrCode, String errorString)
ResultObjectEntry (Result result)
6.26.13 ResultObjectSubEntry
NanoLib sends you an instance of this class if the function returns an object sub-entry. The class inherits the public functions / protected attributes from the result class and has the following public member functions: getResult () Returns the device ID vector if a function call had success.
ObjectSubEntry getResult ()
Returns const ObjectSubEntry

Version: doc 1.0.2 / NanoLib 1.1.2

42

6 Classes / functions reference
ResultObjectSubEntry () The following functions aid in defining the exact object sub-entry result:
ResultObjectSubEntry (ObjectSubEntry result)
ResultObjectSubEntry (String errorString)
ResultObjectSubEntry (NlcErrorCode errCode, String errorString)
ResultObjectSubEntry (NlcErrorCode errCode, long exErrCode, String errorString)
ResultObjectSubEntry (Result result)
6.26.14 ResultProfinetDevices
NanoLib sends you an instance of this class if the function returns a Profinet device. The class inherits the public functions / protected attributes from the result class and has the following public member functions:
getResult () Reads out the Profinet device vector if a function call had success.
ProfinetDeviceVector getResult ()
ResultProfinetDevices () The following functions aid in defining the exact Profinet devices.
ResultProfinetDevices (ProfinetDeviceVector profinetDevices)
ResultProfinetDevices (Result result)
ResultProfinetDevices (string errorText, NlcErrorCode errorCode)
6.26.15 ResultSampleDataArray
NanoLib sends you an instance of this class if the function returns a sample data array. The class inherits the public functions / protected attributes from the result class and has the following public member functions:
getResult () Reads out the data array if a function call had success.
SampleDataVector getResult ()

Version: doc 1.0.2 / NanoLib 1.1.2

43

6 Classes / functions reference

ResultSampleDataArray () The following functions aid in defining the exact Profinet devices.
ResultSampleDataArray (SampleDataVector dataArray)

ResultSampleDataArray (string errorDesc, NlcErrorCode errorCode, uint extendedErrorCode)

ResultSampleDataArray (string errorDesc, NlcErrorCode errorCode)

ResultSampleDataArray (Result result)

6.26.16 ResultSamplerState
NanoLib sends you an instance of this class if the function returns a sampler state.This class inherits the public functions / protected attributes from the result class and has the following public member functions:

getResult () Reads out the sampler state vector if a function call had success.
SamplerState getResult ()

Returns SamplerState>

Unconfigured / Configured / Ready / Running / Completed / Failed / Cancelled

ResultSamplerState () The following functions aid in defining the exact sampler state.
ResultSamplerState (SamplerState state)

ResultSamplerState (String errorDesc, NlcErrorCode errorCode, long extendedErrorCode)de)

ResultSamplerState (ResultSamplerState other)

ResultSamplerState (Result result)

6.27 NlcErrorCode

If something goes wrong, the result classes report one of the error codes listed in this enumeration.

Error code Success GeneralError BusUnavailable CommunicationError
ProtocolError

C: Category D: Description R: Reason C: None. D: No error. R: The operation completed successfully.
C: Unspecified. D: Unspecified error. R: Failure that fits no other category.
C: Bus. D: Hardware bus not available. R: Bus inexistent, cut-off or defect.
C: Communication. D: Communication unreliable. R: Unexpected data, wrong CRC, frame or parity errors, etc.
C: Protocol. D: Protocol error. R: Response after unsupported protocol option, device report unsupported protocol, error in the protocol (say, SDO segment sync bit), etc. R: A response or device report to unsupported protocol (options) or to errors in protocol (say, SDO segment sync bit), etc. R: Unsupported protocol (options) or error in protocol (say, SDO segment sync bit), etc.

Version: doc 1.0.2 / NanoLib 1.1.2

44

6 Classes / functions reference

Error code ODDoesNotExist ODInvalidAccess ODTypeMismatch OperationAborted OperationNotSupported InvalidOperation
InvalidArguments AccessDenied ResourceNotFound ResourceUnavailable OutOfMemory TimeOutError

C: Category D: Description R: Reason C: Object dictionary. D: OD address inexistent. R: No such address in the object dictionary.
C: Object dictionary. D: Access to OD address invalid. R: Attempt to write a read-only, or to read from a write-only, address.
C: Object dictionary. D: Type mismatch. R: Value unconverted to specified type, say, in an attempt to treat a string as a number.
C: Application. D: Process aborted. R: Process cut by application request. Returns only on operation interrupt by callback function, say, from bus- scanning.
C: Common. D: Process unsupported. R: No hardware bus / device support.
C: Common. D: Process incorrect in current context, or invalid with current argument. R: A reconnect attempt to already connected buses / devices. A disconnect attempt to already disconnected ones. A bootloader operation attempt in firmware mode or vice versa.
C: Common. D: Argument invalid. R: Wrong logic or syntax.
C: Common. D: Access is denied. R: Lack of rights or capabilities to perform the requested operation.
C: Common. D: Specified item not found. R: Hardware bus, protocol, device, OD address on device, or file was not found.
C: Common. D: Specified item not found. R: busy, inexistent, cut-off or defect.
C: Common. D: Insufficient memory. R: Too little memory to process this command.
C: Common. D: Process timed out. R: Return after time-out expired. Timeout may be a device response time, a time to gain shared or exclusive resource access, or a time to switch the bus / device to a suitable state.

6.28 NlcCallback

This parent class for callbacks has the following public member function:

callback () ResultVoid callback ()

Returns

ResultVoid

6.29 NlcDataTransferCallback

Use this callback class for data transfers (firmware update, NanoJ upload etc.).
1. For a firmware upload: Define a “co-class” extending this one with a custom callback method implementation.
2. Use the “co-class’s” instances in NanoLibAccessor.uploadFirmware () calls.
The main class itself has the following public member function:

callback () ResultVoid callback (DataTransferInfo info, int data)

Returns

ResultVoid

6.30 NlcScanBusCallback

Use this callback class for bus scanning.

Version: doc 1.0.2 / NanoLib 1.1.2

45

6 Classes / functions reference

1. Define a “co-class” extending this one with a custom callback method implementation. 2. Use the “co-class’s” instances in NanoLibAccessor.scanDevices () calls. The main class itself has the following public member function.
callback ()
ResultVoid callback(BusScanInfo info, DeviceIdVector devicesFound, int data)
Returns ResultVoid
6.31 NlcLoggingCallback
Use this callback class for logging callbacks. 1. Define a class that extends this class with a custom callback method implementation 2. Use a pointer to its instances in order to set a callback by NanoLibAccessor >
setLoggingCallback (…).
void callback (String payload_str, String formatted_str, String logger_name, long log_level, java.math.BigInteger time_since_epoch, long thread_id)

6.32 SamplerInterface
Use this class to configure, start and stop the sampler, or to get sampled data and fetch a sampler’s status or last error. The class has the following public member functions.

configure () Configures a sampler.
ResultVoid configure (DeviceHandle deviceHandle, SamplerConfiguration samplerConfiguration)

Parameters [in] deviceHandle [in] samplerConfiguration
Returns ResultVoid

Specifies what device to configure the sampler for. Specifies the values of configuration attributes. Confirms that a void function has run.

getData () Gets the sampled data.
ResultSampleDataArray getData (DeviceHandle deviceHandle)

Parameters [in] deviceHandle Returns ResultSampleDataArray

Specifies what device to get the data for.
Delivers the sampled data, which can be an empty array if samplerNotify is active on start.

getLastError () Gets a sampler’s last error.
ResultVoid getLastError (DeviceHandle deviceHandle)

Returns ResultVoid

Confirms that a void function has run.

Version: doc 1.0.2 / NanoLib 1.1.2

46

6 Classes / functions reference

getState () Gets a sampler’s status.
ResultSamplerState getState (DeviceHandle deviceHandle)

Returns ResultSamplerState

Delivers the sampler state.

start () Starts a sampler.
ResultVoid start (DeviceHandle deviceHandle, SamplerNotify samplerNotify, long applicationData)

Parameters [in] deviceHandle [in] SamplerNotify [in] applicationData
Returns ResultVoid

Specifies what device to start the sampler for.
Specifies what optional info to report (can be nullptr).
Option: Forwards application-related data (a user-defined 8-bit array of value / device ID / index, or a datetime, a variable’s / function’s pointer, etc.) to samplerNotify.
Confirms that a void function has run.

stop () Stops a sampler.
ResultVoid stop (DeviceHandle deviceHandle)

Parameters [in] deviceHandle Returns ResultVoid

Specifies what device to stop the sampler for. Confirms that a void function has run.

6.33 SamplerConfiguration struct

This struct contains the data sampler’s configuration options (static or not).

Public attributes

std::vector trackedAddresses

Up to 12 OD addresses to be sampled.

uint32_t

version

A structure’s version.

uint32_t

durationMilliseconds

Sampling duration in ms, from 1 to 65535

uint16_t

periodMilliseconds

Sampling period in ms.

uint16_t

numberOfSamples

Samples amount.

uint16_t

preTriggerNumberOfSamples

Samples pre-trigger amount.

bool

usingSoftwareImplementation

Use software implementation.

bool

usingNewFWSamplerImplementation Use FW implementation for devices with a

FW version v24xx or newer.

SamplerMode

mode

Normal, repetitive or continuous sampling.

SamplerTriggerCondition triggerCondition

Start trigger conditions: TC_FALSE = 0x00 TC_TRUE = 0x01 TC_SET = 0x10 TC_CLEAR = 0x11 TC_RISING_EDGE = 0x12 TC_FALLING_EDGE = 0x13 TC_BIT_TOGGLE = 0x14 TC_GREATER = 0x15

Version: doc 1.0.2 / NanoLib 1.1.2

47

6 Classes / functions reference

SamplerTrigger

SamplerTrigger

TC_GREATER_OR_EQUAL = 0x16 TC_LESS = 0x17 TC_LESS_OR_EQUAL = 0x18 TC_EQUAL = 0x19 TC_NOT_EQUAL = 0x1A TC_ONE_EDGE = 0x1B TC_MULTI_EDGE = 0x1C, OdIndex, triggerValue
A trigger to start a sampler?

Static public attributes
static constexpr size_t SAMPLER_CONFIGURATION_VERSION = 0x01000000 static constexpr size_t MAX_TRACKED_ADDRESSES = 12
6.34 SamplerNotify
Use this class to activate sampler notifications when you start a sampler. The class has the following public member function.

notify () Delivers a notification entry.
void notify (ResultVoid lastError, SamplerState samplerState, SampleDataVector sampleDatas, long applicationData)

Parameters [in] lastError [in] samplerState
[in] sampleDatas [in] applicationData

Reports the last error occurred while sampling. Reports the sampler status at notification time: Unconfigured / Configured / Ready / Running / Completed / Failed / Cancelled. Reports the sampled-data array. Reports application- specific data.

6.35 SampleData struct

This struct contains the sampled data.

uin64_t iterationNumber

Starts at 0 and only increases in repetitive mode.

std::vector Contains he array of sampled values.

6.36 SampledValue struct

This struct contains the sampled values.

in64_t value uin64_t CollectTimeMsec

Contains the value of a tracked OD address.
Contains the collection time in milliseconds, relative to the sample beginning.

6.37 SamplerTrigger struct

This struct contains the trigger settings of the sampler.

SamplerTriggerCondition condition

The trigger condition:TC_FALSE = 0x00 TC_TRUE = 0x01 TC_SET = 0x10 TC_CLEAR = 0x11 TC_RISING_EDGE = 0x12

Version: doc 1.0.2 / NanoLib 1.1.2

48

6 Classes / functions reference

OdIndex uin32_t value

TC_FALLING_EDGE = 0x13 TC_BIT_TOGGLE = 0x14 TC_GREATER = 0x15 TC_GREATER_OR_EQUAL = 0x16 TC_LESS = 0x17 TC_LESS_OR_EQUAL = 0x18 TC_EQUAL = 0x19 TC_NOT_EQUAL = 0x1A TC_ONE_EDGE = 0x1B TC_MULTI_EDGE = 0x1C
The trigger’s OdIndex (address).
Condition value or bit number (starting from bit zero).

6.38 Serial struct

Find here your serial communication options and the following public attributes:

:string SerialBaudRate string SerialParity

BAUD_RATE_OPTIONS_NAME = “serial baud rate” baudRate =SerialBaudRate struct PARITY_OPTIONS_NAME = “serial parity” parity = SerialParity struct

6.39 SerialBaudRate struct

Find here your serial communication baud rate and the following public attributes:

string string string string string string string string string string

BAUD_RATE_7200 = “7200” BAUD_RATE_9600 = “9600” BAUD_RATE_14400 = “14400” BAUD_RATE_19200 = “19200” BAUD_RATE_38400 = “38400” BAUD_RATE_56000 = “56000” BAUD_RATE_57600 = “57600” BAUD_RATE_115200 = “115200” BAUD_RATE_128000 = “128000” BAUD_RATE_256000 = “256000”

6.40 SerialParity struct

Find here your serial parity options and the following public attributes:

string string string string string

NONE = “none” ODD = “odd” EVEN = “even” MARK = “mark” SPACE = “space”

Version: doc 1.0.2 / NanoLib 1.1.2

49

7 Licenses

7 Licenses

NanoLib API interface and example source code are licensed by Nanotec Electronic GmbH & Co. KG under the Creative Commons Attribution 3.0 Unported License (CC BY). Library parts provided in binary format (core and fieldbus communication libraries) are licensed under the Creative Commons AttributionNoDerivatives 4.0 International License (CC BY ND).

Creative Commons
The following human-readable summary won’t substitute the license(s) itself. You can find the respective license at creativecommons.org and linked below. You are free to:

CC BY 3.0
Share: See right. Adapt: Remix, transform, and build upon the
material for any purpose, even commercially.

CC BY-ND 4.0
Share: Copy and redistribute the material in any medium or format.

The licensor cannot revoke the above freedoms as long as you obey the following license terms:

CC BY 3.0

CC BY-ND 4.0

Attribution: You must give appropriate credit, Attribution: See left. But: Provide a link to this

provide a link to the license, and indicate if

other license.

changes were made. You may do so in any

No derivatives: If you remix, transform, or build

reasonable manner, but not in any way that sug-

upon the material, you may not distribute the

gests the licensor endorses you or your use.

modified material.

No additional restrictions: You may not apply No additional restrictions: See left. legal terms or technological measures that legally

restrict others from doing anything the license

permits.

Note: You do not have to comply with the license for elements of the material in the public domain or where your use is permitted by an applicable exception or limitation.
Note: No warranties given. The license may not give you all of the permissions necessary for your intended use. For example, other rights such as publicity, privacy, or moral rights may limit how you use the material.

Version: doc 1.0.2 / NanoLib 1.1.2

50

8 Imprint, contact, versions

8 Imprint, contact, versions

©2024 Nanotec Electronic GmbH & Co.KGKapellenstr.685622 FeldkirchenGermanyTel.+49(0) 89 900 686-0Fax+49(0)89 900 [email protected] rights reserved. Error, omission, technical or content change possible without notice. Quoted brands/products are trademarks of their owners and to be treated as such. Original version.

Document 1.0.2 2024.05
1.0.1 2024.04 1.0.0 2024.02

+ Added > Changed # Fixed

Modbus RTU: Fixed timing issues with low baud rates during firmware update.

RESTful: Fixed NanoJ program upload.

NanoLib Modules Sampler: Correct reading of sampled boolean values.

+ Java 11 support for all platforms. + Python 3.11/3.12 support for all platforms. + New logging callback interface (see examples). + Callback sinks for NanoLib Logger. > Update logger to version 1.12.0. > NanoLib Modules Sampler: Support now for Nanotec controller firmware v24xx. > NanoLib Modules Sampler: Change in structure used for sampler configuration. > NanoLib Modules Sampler: Continuous mode is synonymous with endless; the trigger condition is checked once; the number of samples must be 0. > NanoLib Modules Sampler: Normal priority for the thread that collects data in firmware mode. > NanoLib Modules Sampler: Rewritten algorithm to detect transition between Ready & Running state. # NanoLib Core: No more Access Violation (0xC0000005) on closing 2 or more devices using the same bus hardware. # NanoLib Core: No more Segmentation Fault on attaching a PEAK adapter under Linux. # NanoLib Modules Sampler: Correct sampled-values reading in firmware mode. # NanoLib Modules Sampler: Correct configuration of 502X:04. # NanoLib Modules Sampler: Correct mixing of buffers with channels. # NanoLib-Canopen: Increased CAN timeouts for robustness and correct scanning at lower baudrates. # NanoLib-Modbus: VCP detection algorithm for special devices (USB-DA-IO).

Product 1.1.2
1.1.1 1.1.0

Version: doc 1.0.2 / NanoLib 1.1.2

51

References

• Homepage - Creative Commons
• Ixxat | Data communication for CAN, Ethernet and Safety
• Nanotec - Precise and Reliable Motion Control Solutions

Read User Manual Online (PDF format)

Download This Manual (PDF format)

Download this manual  >>