esi.h

Go to the documentation of this file.

#pragma once
 
#include <cstdint>
#include <expected>
#include <filesystem>
#include <nlohmann/json_fwd.hpp>
#include <optional>
#include <string>
#include <string_view>
#include <vector>
 
#include "etg/esi_unit.h"
 
namespace mm::etg {
 
 
// ---------------------------------------------------------------------------------------------
// Shared vocabulary.
//
// These types are used by more than one parent element, so they live at namespace scope rather
// than nested: `Property` appears under Object, DataType and DataType/SubItem; `Text` appears
// under a dozen elements. Nesting them under any one parent would misstate ownership.
// ---------------------------------------------------------------------------------------------
 
struct Text {
  std::string value;
  uint32_t lcId = 0;  
};
 
inline constexpr uint32_t kDefaultLcId = 1033;
 
std::string_view esiText(const std::vector<Text>& texts, uint32_t lcId = kDefaultLcId);
 
struct Property {
  std::string name;
  std::string value;
};
 
enum class AccessMode : uint8_t { Ro, Rw, Wo };
 
enum class StateRestriction : uint8_t { None, PreOp, PreOpSafeOp, PreOpOp, SafeOp, SafeOpOp, Op };
 
enum class Category : uint8_t { Mandatory, Optional, Conditional };
 
enum class PdoMapping : uint8_t { None, Tx, Rx, TxRx };
 
enum class SafetyMapping : uint8_t { None, SafeIn, SafeOut, SafeInOut, SafeParam };
 
enum class SdoAccess : uint8_t { SubIndexAccess, CompleteAccess };
 
struct Access {
  AccessMode mode = AccessMode::Ro;
  StateRestriction readRestrictions = StateRestriction::None;
  StateRestriction writeRestrictions = StateRestriction::None;
};
 
struct MailboxCoe {
  bool sdoInfo = false;
  bool pdoAssign = false;
  bool pdoConfig = false;
  bool pdoUpload = false;
  bool completeAccess = false;
};
 
constexpr std::string_view accessModeName(AccessMode v) {
  switch (v) {
    case AccessMode::Ro:
      return "ro";
    case AccessMode::Rw:
      return "rw";
    case AccessMode::Wo:
      return "wo";
  }
  return "ro";
}
 
constexpr std::string_view categoryName(Category v) {
  switch (v) {
    case Category::Mandatory:
      return "m";
    case Category::Optional:
      return "o";
    case Category::Conditional:
      return "c";
  }
  return "o";
}
 
constexpr std::string_view pdoMappingName(PdoMapping v) {
  switch (v) {
    case PdoMapping::None:
      return "";
    case PdoMapping::Tx:
      return "t";
    case PdoMapping::Rx:
      return "r";
    case PdoMapping::TxRx:
      return "tr";
  }
  return "";
}
 
constexpr std::string_view safetyMappingName(SafetyMapping v) {
  switch (v) {
    case SafetyMapping::None:
      return "";
    case SafetyMapping::SafeIn:
      return "si";
    case SafetyMapping::SafeOut:
      return "so";
    case SafetyMapping::SafeInOut:
      return "sio";
    case SafetyMapping::SafeParam:
      return "sp";
  }
  return "";
}
 
constexpr std::string_view sdoAccessName(SdoAccess v) {
  return v == SdoAccess::CompleteAccess ? "CompleteAccess" : "SubIndexAccess";
}
 
constexpr std::string_view stateRestrictionName(StateRestriction v) {
  switch (v) {
    case StateRestriction::None:
      return "";
    case StateRestriction::PreOp:
      return "PreOP";
    case StateRestriction::PreOpSafeOp:
      return "PreOP_SafeOP";
    case StateRestriction::PreOpOp:
      return "PreOP_OP";
    case StateRestriction::SafeOp:
      return "SafeOP";
    case StateRestriction::SafeOpOp:
      return "SafeOP_OP";
    case StateRestriction::Op:
      return "OP";
  }
  return "";
}
 
// ---------------------------------------------------------------------------------------------
// Dictionary elements.
// ---------------------------------------------------------------------------------------------
 
struct EsiObject {
  struct Flags {
    std::optional<Access> access;
    std::optional<Category> category;
    std::optional<PdoMapping> pdoMapping;
    std::optional<SafetyMapping> safetyMapping;
    std::optional<uint32_t> attribute;      
    std::optional<std::string> transition;  
    std::optional<SdoAccess> sdoAccess;
    std::optional<int32_t> backup;
    std::optional<int32_t> setting;
  };
 
  struct Info {
    struct SubItem;
 
    std::vector<uint8_t> minData;
    std::vector<uint8_t> maxData;
    std::vector<uint8_t> defaultData;
    std::optional<int64_t> minValue;
    std::optional<int64_t> maxValue;
    std::optional<int64_t> defaultValue;
    std::optional<std::string> defaultString;
    std::optional<std::string> displayName;  
    std::optional<uint32_t> unit;            
    bool hasScaling = false;                 
    std::vector<SubItem> subItems;
  };
 
  uint32_t index = 0;
  bool dependOnSlot = false;
  bool dependOnSlotGroup = false;
  bool overwrittenByModule = false;
 
  std::vector<Text> names;
  std::vector<Text> comments;
  std::string type;  
  int32_t bitSize = 0;
  Info info;
  std::optional<Flags> flags;  
  std::vector<Property> properties;
};
 
struct EsiObject::Info::SubItem {
  std::string name;
  Info info;
};
 
struct EsiDataType {
  struct SubItem {
    struct Flags {
      std::optional<Access> access;
      std::optional<Category> category;
      std::optional<PdoMapping> pdoMapping;
      std::optional<SafetyMapping> safetyMapping;
      std::optional<uint32_t> attribute;
      std::optional<int32_t> backup;
      std::optional<int32_t> setting;
    };
 
    std::optional<uint8_t> subIdx;
    std::string name;
    std::vector<Text> displayNames;
    std::string type;  
    std::vector<Text> comments;
    int32_t bitSize = 0;
    int32_t bitOffs = 0;
    std::vector<uint8_t> defaultData;
    std::optional<int64_t> minValue;
    std::optional<int64_t> maxValue;
    std::optional<int64_t> defaultValue;
    std::optional<std::string> defaultString;
    std::optional<Flags> flags;        
    std::vector<Property> properties;  
  };
 
  struct ArrayInfo {
    int64_t lBound = 0;
    int64_t elements = 0;  
  };
 
  struct EnumInfo {
    std::vector<Text> texts;  
    int64_t value = 0;        
  };
 
  std::optional<uint32_t> index;
  std::string name;
  std::optional<std::string> baseType;
  std::vector<Text> comments;
  int32_t bitSize = 0;
  std::vector<ArrayInfo> arrayInfo;
  std::vector<SubItem> subItems;
  std::vector<EnumInfo> enumInfo;
  std::vector<Property> properties;
};
 
struct EsiDictionary {
  std::vector<UnitType> unitTypes;
  std::vector<EsiDataType> dataTypes;
  std::vector<EsiObject> objects;
};
 
struct EsiProfile {
  std::optional<int32_t> profileNo;  
  std::optional<int32_t> addInfo;
  std::optional<int32_t> subAddInfo;
  std::optional<std::string> dictionaryFile;
  std::optional<EsiDictionary> dictionary;
};
 
// ---------------------------------------------------------------------------------------------
// Process data and modular-device elements.
// ---------------------------------------------------------------------------------------------
 
struct EsiPdo {
  struct Entry {
    uint32_t index = 0;
    uint8_t subIndex = 0;
    int32_t bitLen = 0;
    std::vector<Text> names;
    std::optional<std::string> dataType;
 
    bool isPadding() const { return index == 0; }
  };
 
  uint32_t index = 0;
  std::vector<Text> names;
  std::vector<uint32_t> excludes;  
  std::vector<Entry> entries;
  std::optional<int32_t> sm;  
  std::optional<int32_t> su;
  bool fixed = false;
  bool mandatory = false;
  bool isVirtual = false;
  bool overwrittenByModule = false;
};
 
struct EsiSlots {
  struct Slot {
    std::vector<Text> names;
    std::vector<uint32_t> moduleIdents;
    std::optional<uint32_t> defaultModuleIdent;  
    uint32_t minInstances = 0;
    uint32_t maxInstances = 0;
    std::optional<uint32_t> slotGroup;
    std::optional<uint32_t> slotPdoIncrement;
    std::optional<uint32_t> slotIndexIncrement;
  };
 
  struct ModulePdoGroup {
    std::optional<int32_t> alignment;
    std::optional<uint32_t> rxPdo;
    std::optional<uint32_t> txPdo;
  };
 
  std::vector<Slot> slots;
  std::vector<ModulePdoGroup> modulePdoGroups;
  uint32_t slotPdoIncrement = 0;    
  uint32_t slotIndexIncrement = 0;  
  std::optional<uint32_t> maxSlotCount;
  bool downloadModuleIdentList = false;
};
 
// ---------------------------------------------------------------------------------------------
// Top-level descriptions.
// ---------------------------------------------------------------------------------------------
 
struct EsiDevice {
  std::string type;
  std::optional<uint32_t> productCode;
  std::optional<uint32_t> revisionNo;
  std::optional<uint32_t> serialNo;
  std::vector<Text> names;
  std::vector<Text> comments;
  std::string groupType;
  std::string physics;
  bool invisible = false;
  std::optional<MailboxCoe> coe;
 
  std::vector<EsiProfile> profiles;
 
  std::vector<EsiPdo> rxPdos;
  std::vector<EsiPdo> txPdos;
  EsiSlots slots;
};
 
struct EsiModule {
  uint32_t moduleIdent = 0;
  std::string type;
  std::optional<std::string> moduleClass;
  std::optional<int32_t> modulePdoGroup;  
  std::vector<Text> names;
  std::optional<MailboxCoe> coe;
  std::optional<EsiProfile> profile;  
  std::vector<EsiPdo> rxPdos;
  std::vector<EsiPdo> txPdos;
  std::vector<EsiPdo> safetyParaMappings;
};
 
struct EsiFile {
  struct Vendor {
    uint32_t id = 0;
    std::vector<Text> names;
    std::vector<Text> urls;
  };
 
  std::optional<std::string> version;  
  Vendor vendor;
  std::vector<EsiDevice> devices;
  std::vector<EsiModule> modules;
  std::vector<std::string> warnings;
};
 
// ---------------------------------------------------------------------------------------------
// API.
// ---------------------------------------------------------------------------------------------
 
std::expected<EsiFile, std::string> parseEsi(std::string_view xml);
 
std::expected<EsiFile, std::string> parseEsiFile(const std::filesystem::path& path);
 
const EsiDevice* findEsiDevice(const EsiFile& file, std::string_view type);
 
const EsiDevice* findEsiDeviceByProductCode(const EsiFile& file, uint32_t productCode,
                                            std::optional<uint32_t> revisionNo = std::nullopt);
 
const EsiModule* findEsiModule(const EsiFile& file, uint32_t moduleIdent);
 
std::vector<uint32_t> esiSlotModuleIdents(const EsiDevice& device);
 
void to_json(nlohmann::json& j, const Text& v);
void to_json(nlohmann::json& j, const Property& v);
void to_json(nlohmann::json& j, const Access& v);
void to_json(nlohmann::json& j, const MailboxCoe& v);
void to_json(nlohmann::json& j, const EsiObject::Flags& v);
void to_json(nlohmann::json& j, const EsiObject::Info& v);
void to_json(nlohmann::json& j, const EsiObject::Info::SubItem& v);
void to_json(nlohmann::json& j, const EsiObject& v);
void to_json(nlohmann::json& j, const EsiDataType::SubItem::Flags& v);
void to_json(nlohmann::json& j, const EsiDataType::SubItem& v);
void to_json(nlohmann::json& j, const EsiDataType::ArrayInfo& v);
void to_json(nlohmann::json& j, const EsiDataType::EnumInfo& v);
void to_json(nlohmann::json& j, const EsiDataType& v);
void to_json(nlohmann::json& j, const EsiDictionary& v);
void to_json(nlohmann::json& j, const EsiProfile& v);
void to_json(nlohmann::json& j, const EsiPdo::Entry& v);
void to_json(nlohmann::json& j, const EsiPdo& v);
void to_json(nlohmann::json& j, const EsiSlots::Slot& v);
void to_json(nlohmann::json& j, const EsiSlots::ModulePdoGroup& v);
void to_json(nlohmann::json& j, const EsiSlots& v);
void to_json(nlohmann::json& j, const EsiDevice& v);
void to_json(nlohmann::json& j, const EsiModule& v);
void to_json(nlohmann::json& j, const EsiFile::Vendor& v);
void to_json(nlohmann::json& j, const EsiFile& v);
 
}  // namespace mm::etg