Public Types
using	Ptr = std::shared_ptr< LegacyDevice >

using	boot_mode = ifm3d::Device::boot_mode

using	operating_mode = ifm3d::Device::operating_mode

using	trigger_mode = ifm3d::Device::trigger_mode

using	import_flags = ifm3d::Device::import_flags

using	spatial_filter = ifm3d::Device::spatial_filter

using	temporal_filter = ifm3d::Device::temporal_filter

using	mfilt_mask_size = ifm3d::Device::mfilt_mask_size

using	device_family = ifm3d::Device::device_family

Public Types inherited from ifm3d::Device
enum	boot_mode : int { PRODUCTIVE = 0, RECOVERY = 1 }
	Device boot up modes: More...

enum	operating_mode : int { RUN = 0, EDIT = 1 }
	Device operating modes: run (streaming pixel data), edit (configuring the device/applications).

enum	trigger_mode : int { FREE_RUN = 1, SW = 2 }
	Image acquisition trigger modes.

enum	import_flags : int { GLOBAL = 0x1, NET = 0x2, APPS = 0x10 }
	Import flags used when importing a Vision Assistant configuration.

enum	spatial_filter : int { OFF = 0x0, MEDIAN = 0x1, MEAN = 0x2, BILATERAL = 0x3 }
	Convenience constants for spatial filter types.

enum	temporal_filter : int { OFF = 0x0, MEAN = 0x1, ADAPTIVE_EXP = 0x2 }
	Convenience constants for temporal filter types.

enum	mfilt_mask_size : int { _3x3 = 0, _5x5 = 1 }
	Convenient constants for median filter mask sizes.

enum	device_family : int { UNKNOWN = 0, O3D = 1, O3X = 2, O3R = 3 }

enum	swu_version : int { SWU_NOT_SUPPORTED = 0, SWU_V1 = 1, SWU_V2 = 2 }

using	Ptr = std::shared_ptr< Device >

Public Member Functions
	LegacyDevice (const std::string &ip=ifm3d::DEFAULT_IP, const std::uint16_t xmlrpc_port=ifm3d::DEFAULT_XMLRPC_PORT, const std::string &password=ifm3d::DEFAULT_PASSWORD)
	Initializes the device interface utilizing library defaults for password, ip, and xmlrpc port unless explicitly passed in. More...

virtual std::string	Password ()
	The password associated with this Device instance.

virtual std::string	SessionID ()
	Retrieves the active session id.

virtual void	FactoryReset ()
	Sets the device configuration back to the state in which it shipped from the ifm factory.

virtual std::string	RequestSession ()
	Requests an edit-mode session with the device. More...

virtual bool	CancelSession ()
	Explictly stops the current session with the sensor. More...

virtual bool	CancelSession (const std::string &sid)
	Attempts to cancel a session with a particular session id. More...

virtual int	Heartbeat (int hb)
	Heartbeat messages are used to keep a session with the sensor alive. More...

virtual std::unordered_map< std::string, std::string >	NetInfo ()

virtual std::unordered_map< std::string, std::string >	TimeInfo ()

virtual void	SetTemporaryApplicationParameters (const std::unordered_map< std::string, std::string > &params)
	Sets temporary application parameters in run mode. More...

virtual int	ActiveApplication ()
	Returns the integer index of the active application. More...

virtual json	ApplicationList ()
	Delivers basic information about all applications stored on the device. More...

virtual std::vector< std::string >	ApplicationTypes ()
	Lists the valid application types supported by the sensor. More...

virtual std::vector< std::string >	ImagerTypes ()
	Lists the valid imager types supported by the sensor. More...

virtual int	CopyApplication (int idx)
	Creates a new application by copying the configuration of another application. More...

virtual int	CreateApplication (const std::string &type=DEFAULT_APPLICATION_TYPE)
	Creates a new application on the device of the given type. More...

virtual void	DeleteApplication (int idx)
	Deletes the application at the specified index from the sensor. More...

virtual void	SetCurrentTime (int epoch_secs=-1)
	Explicitly sets the current time on the device. More...

virtual std::vector< std::uint8_t >	UnitVectors ()
	For devices that support fetching the Unit Vectors over XML-RPC, this function will return those data as a binary blob.

virtual std::vector< std::uint8_t >	ExportIFMConfig ()
	Exports the entire device configuration in a format compatible with Vision Assistant.

virtual std::vector< std::uint8_t >	ExportIFMApp (int idx)
	Export the application at the specified index into a byte array suitable for writing to a file. More...

virtual void	ImportIFMConfig (const std::vector< std::uint8_t > &bytes, std::uint16_t flags=0x0)
	Imports an entire device configuration from a format compatible with Vision Assistant.

virtual int	ImportIFMApp (const std::vector< std::uint8_t > &bytes)
	Import the IFM-encoded application. More...

virtual void	SetPassword (std::string password="")
	Sets or disable the password on the device. More...

json	ToJSON () override
	Serializes the state of the device to JSON. More...

void	FromJSON (const json &j) override
	Configures the device based on the parameter values of the passed in JSON. More...

void	ForceTrigger () override
	Sends a S/W trigger to the device over XMLRPC. More...

Public Member Functions inherited from ifm3d::Device
	Device (const std::string &ip=ifm3d::DEFAULT_IP, const std::uint16_t xmlrpc_port=ifm3d::DEFAULT_XMLRPC_PORT)
	Initializes the device interface utilizing library defaults for password, ip, and xmlrpc port unless explicitly passed in. More...

virtual	~Device ()
	The dtor will cancel any open edit sessions with the device.

	Device (Device &&)=delete

Device &	operator= (Device &&)=delete

	Device (Device &)=delete

Device &	operator= (Device &)=delete

virtual std::string	IP ()
	The IP address associated with this Device instance.

virtual std::uint16_t	XMLRPCPort ()
	The XMLRPC Port associated with this Device instance.

virtual void	Reboot (const boot_mode &mode=ifm3d::Device::boot_mode::PRODUCTIVE)
	Reboot the device. More...

virtual std::string	DeviceType (bool use_cached=true)
	This is a convenience function for extracting out the device type of the connected device. More...

virtual device_family	WhoAmI ()
	This function can be used to retrieve the family of the connected device. More...

virtual bool	AmI (device_family family)
	This is a convenience function for checking whether a device is one of the specified device family. More...

virtual std::string	DeviceParameter (const std::string &key)
	Convenience accessor for extracting a device parameters (i.e., no edit session created on the device)

virtual std::vector< std::string >	TraceLogs (int count)
	Delivers the trace log from the device A session is not required to call this function. More...

virtual std::string	ToJSONStr ()
	A stringified version of the JSON object returned by `ToJSON()`. More...

virtual void	FromJSONStr (const std::string &jstr)
	Accepts a string with properly formatted/escaped JSON text, converts it to a `json` object, and call `FromJSON()` on it. More...

bool	CheckMinimumFirmwareVersion (unsigned int major, unsigned int minor, unsigned int patch)
	Checks for a minimum ifm device software version. More...

ifm3d::SemVer	FirmwareVersion ()
	get the firmware version of the device

virtual ifm3d::Device::swu_version	SwUpdateVersion ()
	Checks the swupdater version supported by device. More...

Static Public Member Functions
static Ptr	MakeShared (const std::string &ip=ifm3d::DEFAULT_IP, const std::uint16_t xmlrpc_port=ifm3d::DEFAULT_XMLRPC_PORT, const std::string &password=ifm3d::DEFAULT_PASSWORD)
	Factory function for instantiating the proper subclass based on h/w probing. More...

Static Public Member Functions inherited from ifm3d::Device
static std::vector< ifm3d::IFMNetworkDevice >	DeviceDiscovery ()
	This function Provides a convinent way to find all ifm devices on the network. More...

static Ptr	MakeShared (const std::string &ip=ifm3d::DEFAULT_IP, const std::uint16_t xmlrpc_port=ifm3d::DEFAULT_XMLRPC_PORT, const std::string &password=ifm3d::DEFAULT_PASSWORD, bool throwIfUnavailable=true)
	Factory function for instantiating the proper subclass based on h/w probing. More...

Protected Member Functions
void	FromJSON_ (const json &j_curr, const json &j_new, std::function< void(const std::string &, const std::string &)> SetFunc, std::function< void()> SaveFunc, const std::string &name, int idx=-1)
	Handles parsing a selected sub-tree of a potential input JSON file, setting the parameters as appropriate on the device, and saving them persistently. More...

json	ToJSON_ (const bool open_session=true)

json	getApplicationInfosToJSON ()

Protected Member Functions inherited from ifm3d::Device
int	DeviceID ()
	Implements the serialization of the device state to JSON. More...

bool	checkDeviceID (int deviceID, int minID, int maxID)

std::shared_ptr< XMLRPCWrapper >	XWrapper ()

Static Protected Member Functions
static bool	getAppJSON (int index, const json &j, json &app)
	Return json of an app with given index from device configuration json. More...

Protected Attributes
std::unique_ptr< Impl >	pImpl

Protected Attributes inherited from ifm3d::Device
std::unique_ptr< Impl >	pImpl

std::string	device_type_
	The cached device type of the connected device.

Constructor & Destructor Documentation

◆ LegacyDevice()

ifm3d::LegacyDevice::LegacyDevice	(	const std::string &	ip = `ifm3d::DEFAULT_IP`,
		const std::uint16_t	xmlrpc_port = `ifm3d::DEFAULT_XMLRPC_PORT`,
		const std::string &	password = `ifm3d::DEFAULT_PASSWORD`
	)

Initializes the device interface utilizing library defaults for password, ip, and xmlrpc port unless explicitly passed in.

Parameters

[in]	ip	The ip address of the device
[in]	xmlrpc_port	The tcp port the sensor's XMLRPC server is listening on
[in]	password	Password required for establishing an "edit session" with the sensor. Edit sessions allow for mutating device parameters and persisting those changes.

Member Function Documentation

◆ ActiveApplication()

virtual int ifm3d::LegacyDevice::ActiveApplication ( )

virtual

Returns the integer index of the active application.

A negative number indicates no application is marked as active on the sensor.

◆ ApplicationList()

virtual json ifm3d::LegacyDevice::ApplicationList ( )

virtual

Delivers basic information about all applications stored on the device.

A call to this function does not require establishing a session with the device.

The returned information is encoded as an array of JSON objects. Each object in the array is basically a dictionary with the following keys: 'index', 'id', 'name', 'description', 'active'

Returns: A JSON encoding of the application information

Exceptions

ifm3d::Error upon error

◆ ApplicationTypes()

virtual std::vector<std::string> ifm3d::LegacyDevice::ApplicationTypes ( )

virtual

Lists the valid application types supported by the sensor.

Returns: A vector of strings listing the available types of applications supported by the sensor. Each element of the vector is a string suitable to passing to CreateApplication.

Exceptions

ifm3d::Error upon error

◆ CancelSession() [1/2]

virtual bool ifm3d::LegacyDevice::CancelSession ( )

virtual

Explictly stops the current session with the sensor.

NOTE: This function returns a boolean indicating the success/failure of cancelling the session. The reason we return a bool and explicitly supress exceptions is because we want to cancel any open sessions in the device dtor and we do not want to throw in the dtor.

Returns: true if the session was cancelled properly, false if an exception was caught trying to close the session. Details will be logged.

◆ CancelSession() [2/2]

virtual bool ifm3d::LegacyDevice::CancelSession ( const std::string & sid )

virtual

Attempts to cancel a session with a particular session id.

Returns: true if the session was cancelled properly, false if an exception was caught trying to close the session. Details will be logged.

◆ CopyApplication()

virtual int ifm3d::LegacyDevice::CopyApplication ( int idx )

virtual

Creates a new application by copying the configuration of another application.

The device will generate an ID for the new application and put it on a free index.

Parameters

[in] idx The index of the application to copy

Returns: Index of the new application

Exceptions

ifm3d::Error upon error

◆ CreateApplication()

virtual int ifm3d::LegacyDevice::CreateApplication ( const std::string & type = DEFAULT_APPLICATION_TYPE )

virtual

Creates a new application on the device of the given type.

To figure out valid types, you should call the AvailableApplicationTypes() method.

Upon creation of the application, the embedded device will initialize all parameters as necessary based on the type. However, based on the type, the application may not be in an activatable state. That is, it can be created and saved on the device, but it cannot be marked as active.

Parameters

[in] type The (optional) application type to create. By default, it will create a new "Device" application.

Returns: The index of the new application.

◆ DeleteApplication()

virtual void ifm3d::LegacyDevice::DeleteApplication ( int idx )

virtual

Deletes the application at the specified index from the sensor.

Parameters

[in] idx The index of the application to delete throw ifm3d::Error upon error

◆ ExportIFMApp()

virtual std::vector<std::uint8_t> ifm3d::LegacyDevice::ExportIFMApp ( int idx )

virtual

Export the application at the specified index into a byte array suitable for writing to a file.

The exported bytes represent the IFM serialization of an application.

This function provides compatibility with tools like IFM's Vision Assistant.

Parameters

[in] idx The index of the application to export.

Returns: A vector of bytes representing the IFM serialization of the exported application.

Exceptions

ifm3d::Error upon error

◆ ForceTrigger()

void ifm3d::LegacyDevice::ForceTrigger ( )

overridevirtual

Sends a S/W trigger to the device over XMLRPC.

The O3X does not S/W trigger over PCIC, so, this function has been developed specficially for it. For other sensors, this is a NOOP.

Reimplemented from ifm3d::Device.

◆ FromJSON()

void ifm3d::LegacyDevice::FromJSON ( const json & j )

overridevirtual

Configures the device based on the parameter values of the passed in JSON.

This function is the way to tune the device/application/imager/etc. parameters.

Parameters

[in] json A json object encoding a camera configuration to apply to the hardware.

Device parameters are processed and saved persistently

Exceptions

ifm3d::Error upon error - if this throws an exception, you are encouraged to check the log file as a best effort is made to be as descriptive as possible as to the specific error that has occured.

Reimplemented from ifm3d::Device.

◆ FromJSON_()

void ifm3d::LegacyDevice::FromJSON_	(	const json &	j_curr,
		const json &	j_new,
		std::function< void(const std::string &, const std::string &)>	SetFunc,
		std::function< void()>	SaveFunc,
		const std::string &	name,
		int	idx = `-1`
	)

protected

Handles parsing a selected sub-tree of a potential input JSON file, setting the parameters as appropriate on the device, and saving them persistently.

Parameters

[in]	j_curr	The current configuration
[in]	j_new	The desired configuration
[in]	SetFunc	The setter function to call for each parameter
[in]	SaveFunc	The function to call to persist the values
[in]	name	A descriptive name for the sub-tree (used to make log messages useful).
[in]	idx	An application index to put into edit mode prior to setting parameters.

◆ getAppJSON()

static bool ifm3d::LegacyDevice::getAppJSON	(	int	index,
		const json &	j,
		json &	app
	)

staticprotected

Return json of an app with given index from device configuration json.

Parameters

[in]	index	Index of application to return
[in]	j	The current configuration
[out]	app	Output json of the application when found or empty json

Returns: True when application was found

◆ Heartbeat()

virtual int ifm3d::LegacyDevice::Heartbeat ( int hb )

virtual

Heartbeat messages are used to keep a session with the sensor alive.

This function sends a heartbeat message to the sensor and sets when the next heartbeat message is required.

Parameters

[in] hb The time (seconds) of when the next heartbeat message will be required.

Returns: The current timeout interval in seconds for heartbeat messages.

Exceptions

ifm3d::Error upon error

◆ ImagerTypes()

virtual std::vector<std::string> ifm3d::LegacyDevice::ImagerTypes ( )

virtual

Lists the valid imager types supported by the sensor.

Returns: A vector of strings listing the available types of imagers supported by the sensor.

Exceptions

ifm3d::Error upon error

◆ ImportIFMApp()

virtual int ifm3d::LegacyDevice::ImportIFMApp ( const std::vector< std::uint8_t > & bytes )

virtual

Import the IFM-encoded application.

This function provides compatibility with tools like IFM's Vision Assistant. An application configuration exported from VA, can be imported using this function.

Parameters

[in] bytes The raw bytes from the zip'd JSON file. NOTE: This function will base64 encode the data for tranmission over XML-RPC.

Returns: The index of the imported application.

◆ MakeShared()

static Ptr ifm3d::LegacyDevice::MakeShared	(	const std::string &	ip = `ifm3d::DEFAULT_IP`,
		const std::uint16_t	xmlrpc_port = `ifm3d::DEFAULT_XMLRPC_PORT`,
		const std::string &	password = `ifm3d::DEFAULT_PASSWORD`
	)

static

Factory function for instantiating the proper subclass based on h/w probing.

This function provides a convenient way for users of the library to write hardware independent code. This function probes the connected hardware and returns a proper subclass based upon the returned DeviceType. In the event that the hardware is not connected, the error is trapped and an instance of the base class is returned. The net result of not having an instance of a subclass is: 1) worse performance, 2) errors will come back from the sensor rather than the library – some of which may be hard to debug.

Parameters

[in]	ip	The ip address of the device
[in]	xmlrpc_port	The tcp port the sensor's XMLRPC server is listening on
[in]	password	Password required for establishing an "edit session" with the sensor. Edit sessions allow for mutating device parameters and persisting those changes.

◆ RequestSession()

virtual std::string ifm3d::LegacyDevice::RequestSession ( )

virtual

Requests an edit-mode session with the device.

In order to (permanently) mutate parameters on the device, an edit session needs to be established. Only a single edit sesson may be established at any one time with the device (think of it as a global mutex on the device state – except if you ask for the mutex and it is already taken, an exception will be thrown).

Most typical use-cases for end-users will not involve establishing an edit-session with the device. To mutate device parameters, the FromJSON family of functions should be used, which, under-the-hood, on the user's behalf, will establish the edit session and gracefully close it. There is an exception. For users who plan to modulate imager parameters (temporary parameters) on the fly while running the framegrabber, managing the session manually is necessary. For this reason, we expose this method in the public Device interface.

NOTE: The session timeout is implicitly set to ifm3d::MAX_HEARTBEAT after the session has been successfully established.

Returns: The session id issued or accepted by the device (see IFM3D_SESSION_ID environment variable)

Exceptions

ifm3d::Error if an error is encountered.

◆ SetCurrentTime()

virtual void ifm3d::LegacyDevice::SetCurrentTime ( int epoch_secs = -1 )

virtual

Explicitly sets the current time on the device.

Parameters

[in] epoch_secs Time since the Unix epoch in seconds. A value less than 0 will implicitly set the time to the current system time.

◆ SetPassword()

virtual void ifm3d::LegacyDevice::SetPassword ( std::string password = "" )

virtual

Sets or disable the password on the device.

Parameters

[in] password is the password string. If the password is blank, password is disabled

Exceptions

ifm3d::Error upon error

◆ SetTemporaryApplicationParameters()

virtual void ifm3d::LegacyDevice::SetTemporaryApplicationParameters ( const std::unordered_map< std::string, std::string > & params )

virtual

Sets temporary application parameters in run mode.

The changes are not persistent and are lost when entering edit mode or turning the device off. The parameters "ExposureTime" and "ExposureTimeRatio" of the imager configuration are supported. All additional parameters are ignored (for now). Exposure times are clamped to their allowed range, depending on the exposure mode. The user must provide the complete set of parameters depending on the exposure mode, i.e., "ExposureTime" only for single exposure modes and both "ExposureTime" and "ExposureTimeRatio" for double exposure modes. Otherwise, behavior is undefined.

Parameters

[in] params The parameters to set on the device.

Exceptions

ifm3d::Error upon error

◆ ToJSON()

json ifm3d::LegacyDevice::ToJSON ( )

overridevirtual

Serializes the state of the device to JSON.

The JSON interface returned here is the excellent JSON for Modern C++.

This function (along with its std::string equivalent ToJSONStr()) provides the primary gateway into obtaining the current parameter settings for the device and PMD imager. Data returned from this function can be manipulated as a json object, then fed into FromJSON(...) to mutate parameter settings on the device.

Returns: A JSON object representation of the current state of the hardware.

Exceptions

ifm3d::Error upon error

Reimplemented from ifm3d::Device.

The documentation for this class was generated from the following file:

ifm3d/device/legacy_device.h

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Constructor & Destructor Documentation

◆ LegacyDevice()

Member Function Documentation

◆ ActiveApplication()

◆ ApplicationList()

◆ ApplicationTypes()

◆ CancelSession() [1/2]

◆ CancelSession() [2/2]

◆ CopyApplication()

◆ CreateApplication()

◆ DeleteApplication()

◆ ExportIFMApp()

◆ ForceTrigger()

◆ FromJSON()

◆ FromJSON_()

◆ getAppJSON()

◆ Heartbeat()

◆ ImagerTypes()

◆ ImportIFMApp()

◆ MakeShared()

◆ RequestSession()

◆ SetCurrentTime()

◆ SetPassword()

◆ SetTemporaryApplicationParameters()

◆ ToJSON()