device.h

// -*- c++ -*-
/*
 * Copyright 2018-present ifm electronic, gmbh
 * Copyright 2017 Love Park Robotics, LLC
 * SPDX-License-Identifier: Apache-2.0
 */
 
#ifndef IFM3D_DEVICE_DEVICE_H
#define IFM3D_DEVICE_DEVICE_H
 
#include <cstdint>
#include <string>
#include <vector>
#include <ifm3d/common/json.hpp>
#include <ifm3d/device/device_export.h>
#include <ifm3d/device/ifm_network_device.h>
#include <ifm3d/device/semver.h>
 
namespace ifm3d
{
  extern IFM3D_DEVICE_EXPORT const std::string DEFAULT_IP;
  extern IFM3D_DEVICE_EXPORT const std::uint16_t DEFAULT_XMLRPC_PORT;
  extern IFM3D_DEVICE_EXPORT const int DEFAULT_PCIC_PORT;
  extern IFM3D_DEVICE_EXPORT const std::uint16_t PCIC_PORT;
  extern IFM3D_DEVICE_EXPORT const std::string DEFAULT_PASSWORD;
  extern IFM3D_DEVICE_EXPORT const int MAX_HEARTBEAT;
  extern IFM3D_DEVICE_EXPORT const std::size_t SESSION_ID_SZ;
  extern IFM3D_DEVICE_EXPORT const std::string DEFAULT_SESSION_ID;
  extern IFM3D_DEVICE_EXPORT const std::string DEFAULT_APPLICATION_TYPE;
  extern IFM3D_DEVICE_EXPORT const long DEFAULT_CURL_CONNECT_TIMEOUT;
  extern IFM3D_DEVICE_EXPORT const long DEFAULT_CURL_TRANSACTION_TIMEOUT;
 
  extern IFM3D_DEVICE_EXPORT const int DEV_O3D_MIN;
  extern IFM3D_DEVICE_EXPORT const int DEV_O3D_MAX;
  extern IFM3D_DEVICE_EXPORT const int DEV_O3R_MIN;
  extern IFM3D_DEVICE_EXPORT const int DEV_O3R_MAX;
  extern IFM3D_DEVICE_EXPORT const int DEV_O3X_MIN;
  extern IFM3D_DEVICE_EXPORT const int DEV_O3X_MAX;
  extern IFM3D_DEVICE_EXPORT const std::string ASSUME_DEVICE;
 
  extern IFM3D_DEVICE_EXPORT const unsigned int O3D_TIME_SUPPORT_MAJOR;
  extern IFM3D_DEVICE_EXPORT const unsigned int O3D_TIME_SUPPORT_MINOR;
  extern IFM3D_DEVICE_EXPORT const unsigned int O3D_TIME_SUPPORT_PATCH;
 
  extern IFM3D_DEVICE_EXPORT const unsigned int O3D_TMP_PARAMS_SUPPORT_MAJOR;
  extern IFM3D_DEVICE_EXPORT const unsigned int O3D_TMP_PARAMS_SUPPORT_MINOR;
  extern IFM3D_DEVICE_EXPORT const unsigned int O3D_TMP_PARAMS_SUPPORT_PATCH;
 
  extern IFM3D_DEVICE_EXPORT const unsigned int
    O3D_INTRINSIC_PARAM_SUPPORT_MAJOR;
  extern IFM3D_DEVICE_EXPORT const unsigned int
    O3D_INTRINSIC_PARAM_SUPPORT_MINOR;
  extern IFM3D_DEVICE_EXPORT const unsigned int
    O3D_INTRINSIC_PARAM_SUPPORT_PATCH;
 
  extern IFM3D_DEVICE_EXPORT const unsigned int
    O3D_INVERSE_INTRINSIC_PARAM_SUPPORT_MAJOR;
  extern IFM3D_DEVICE_EXPORT const unsigned int
    O3D_INVERSE_INTRINSIC_PARAM_SUPPORT_MINOR;
  extern IFM3D_DEVICE_EXPORT const unsigned int
    O3D_INVERSE_INTRINSIC_PARAM_SUPPORT_PATCH;
 
  extern IFM3D_DEVICE_EXPORT const unsigned int
    O3X_DISTANCE_NOISE_IMAGE_SUPPORT_MAJOR;
  extern IFM3D_DEVICE_EXPORT const unsigned int
    O3X_DISTANCE_NOISE_IMAGE_SUPPORT_MINOR;
  extern IFM3D_DEVICE_EXPORT const unsigned int
    O3X_DISTANCE_NOISE_IMAGE_SUPPORT_PATCH;
 
  enum class pixel_format : std::uint32_t
  {
    FORMAT_8U = 0,
    FORMAT_8S = 1,
    FORMAT_16U = 2,
    FORMAT_16S = 3,
    FORMAT_32U = 4,
    FORMAT_32S = 5,
    FORMAT_32F = 6,
    FORMAT_64U = 7,
    FORMAT_64F = 8,
    FORMAT_16U2 = 9,
    FORMAT_32F3 = 10
  };
 
  enum class image_chunk : std::uint32_t
  {
    RADIAL_DISTANCE_IMAGE = 100,
    NORM_AMPLITUDE_IMAGE = 101, // normalized amplitude
    AMPLITUDE_IMAGE = 103,
    GRAYSCALE_IMAGE = 104, // ambient light
    RADIAL_DISTANCE_NOISE = 105,
    REFLECTIVITY = 107,
    CARTESIAN_X_COMPONENT = 200,
    CARTESIAN_Y_COMPONENT = 201,
    CARTESIAN_Z_COMPONENT = 202,
    CARTESIAN_ALL = 203,
    UNIT_VECTOR_ALL = 223,
    MONOCHROM_2D_12BIT = 250,
    MONOCHROM_2D = 251,
    JPEG_IMAGE = 260,
    CONFIDENCE_IMAGE = 300,
    DIAGNOSTIC = 302,
    JSON_DIAGNOSTIC = 305,
    EXTRINSIC_CALIB = 400,
    INTRINSIC_CALIB = 401,
    INVERSE_INTRINSIC_CALIBRATION = 402,
    TOF_INFO = 420,
    O3R_DISTANCE_IMAGE_INFO [[deprecated]] =
      static_cast<uint32_t>(ifm3d::image_chunk::TOF_INFO),
    RGB_INFO = 421,
    O3R_RGB_IMAGE_INFO [[deprecated]] =
      static_cast<uint32_t>(ifm3d::image_chunk::RGB_INFO),
    JSON_MODEL = 500,
    ALGO_DEBUG = 900,
    O3R_ODS_OCCUPANCY_GRID = 1000,
    O3R_ODS_INFO = 1001,
  };
 
  class XMLRPCWrapper;
 
  class IFM3D_DEVICE_EXPORT Device
  {
  public:
    using Ptr = std::shared_ptr<Device>;
 
    enum class boot_mode : int
    {
      PRODUCTIVE = 0,
      RECOVERY = 1
    };
 
    enum class operating_mode : int
    {
      RUN = 0,
      EDIT = 1
    };
 
    enum class trigger_mode : int
    {
      FREE_RUN = 1,
      SW = 2
    };
 
    enum class import_flags : int
    {
      GLOBAL = 0x1,
      NET = 0x2,
      APPS = 0x10
    };
 
    enum class spatial_filter : int
    {
      OFF = 0x0,
      MEDIAN = 0x1,
      MEAN = 0x2,
      BILATERAL = 0x3
    };
 
    enum class temporal_filter : int
    {
      OFF = 0x0,
      MEAN = 0x1,
      ADAPTIVE_EXP = 0x2
    };
 
    enum class mfilt_mask_size : int
    {
      _3x3 = 0,
      _5x5 = 1
    };
 
    enum class device_family : int
    {
      UNKNOWN = 0,
      O3D = 1,
      O3X = 2,
      O3R = 3,
    };
 
    enum class swu_version : int
    {
      SWU_NOT_SUPPORTED = 0,
      SWU_V1 = 1,
      SWU_V2 = 2
    };
 
    static std::vector<ifm3d::IFMNetworkDevice> DeviceDiscovery();
 
    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);
 
    Device(const std::string& ip = ifm3d::DEFAULT_IP,
           const std::uint16_t xmlrpc_port = ifm3d::DEFAULT_XMLRPC_PORT);
 
    virtual ~Device();
 
    // Based on our mileage with `libo3d3xx`, disabling copy and move semantics
    // on the device class has not been an issue, so, we do that here too.
    Device(Device&&) = delete;
    Device& operator=(Device&&) = delete;
    Device(Device&) = delete;
    Device& operator=(Device&) = delete;
 
    // Accessors/Mutators
 
    virtual std::string IP();
 
    virtual std::uint16_t XMLRPCPort();
 
    virtual void Reboot(
      const boot_mode& mode = ifm3d::Device::boot_mode::PRODUCTIVE);
 
    virtual void ForceTrigger();
 
    virtual std::string DeviceType(bool use_cached = true);
 
    virtual device_family WhoAmI();
 
    virtual bool AmI(device_family family);
 
    virtual std::string DeviceParameter(const std::string& key);
 
    virtual std::vector<std::string> TraceLogs(int count);
 
    virtual json ToJSON();
 
    virtual std::string ToJSONStr();
 
    virtual void FromJSON(const json& j);
 
    virtual void FromJSONStr(const std::string& jstr);
 
    bool CheckMinimumFirmwareVersion(unsigned int major,
                                     unsigned int minor,
                                     unsigned int patch);
 
    ifm3d::SemVer FirmwareVersion();
 
    virtual ifm3d::Device::swu_version SwUpdateVersion();
 
  protected:
    class Impl;
    std::unique_ptr<Impl> pImpl;
 
    std::string device_type_;
 
    int DeviceID();
    bool checkDeviceID(int deviceID, int minID, int maxID);
 
    std::shared_ptr<XMLRPCWrapper> XWrapper();
 
  }; // end: class Device
 
} // end: namespace ifm3d
 
#endif // IFM3D_DEVICE_DEVICE_H