coe_utilities.h

Go to the documentation of this file.

/*      File: coe_utilities.h
 *       This file is part of the program ethercatcpp-core
 *       Program description : EtherCAT driver libraries for UNIX
 *       Copyright (C) 2017-2024 -  Robin Passama (LIRMM / CNRS) Arnaud Meline
 * (LIRMM / CNRS) Benjamin Navarro (LIRMM / CNRS). All Right reserved.
 *
 *       This software is free software: you can redistribute it and/or modify
 *       it under the terms of the CeCILL-C license as published by
 *       the CEA CNRS INRIA, either version 1
 *       of the License, or (at your option) any later version.
 *       This software is distributed in the hope that it will be useful,
 *       but WITHOUT ANY WARRANTY without even the implied warranty of
 *       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 *       CeCILL-C License for more details.
 *
 *       You should have received a copy of the CeCILL-C License
 *       along with this software. If not, it can be found on the official
 * website of the CeCILL licenses family (http://www.cecill.info/index.en.html).
 */
#pragma once
#include <cstdint>
#include <map>
#include <string_view>
#include <vector>
#include <cmath>
 
namespace ethercatcpp {
 
class SlaveDevice;
 
namespace coe {
 
constexpr const uint16_t coe_rx_pdo_map_1 = 0x1600;
constexpr const uint16_t coe_rx_pdo_map_2 = 0x1601;
constexpr const uint16_t coe_rx_pdo_map_3 = 0x1602;
constexpr const uint16_t coe_rx_pdo_map_4 = 0x1603;
 
constexpr const uint16_t coe_tx_pdo_map_1 = 0x1A00;
constexpr const uint16_t coe_tx_pdo_map_2 = 0x1A01;
constexpr const uint16_t coe_tx_pdo_map_3 = 0x1A02;
constexpr const uint16_t coe_tx_pdo_map_4 = 0x1A03;
 
constexpr const uint16_t coe_rx_pdo_param_1 = 0x1400;
constexpr const uint16_t coe_rx_pdo_param_2 = 0x1401;
constexpr const uint16_t coe_rx_pdo_param_3 = 0x1402;
constexpr const uint16_t coe_rx_pdo_param_4 = 0x1403;
 
constexpr const uint16_t coe_tx_pdo_param_1 = 0x1800;
constexpr const uint16_t coe_tx_pdo_param_2 = 0x1801;
constexpr const uint16_t coe_tx_pdo_param_3 = 0x1802;
constexpr const uint16_t coe_tx_pdo_param_4 = 0x1803;
 
static constexpr uint16_t coe_rx_pdo_assign = 0x1c12;
static constexpr uint16_t coe_tx_pdo_assign = 0x1c13;
 
class ObjectDictionary {
public:
    struct DictionaryEntry {
        uint16_t addr;
        uint8_t subindex;
        uint8_t bits;
    };
 
    using entry = DictionaryEntry;
 
    ObjectDictionary() = default;
    ~ObjectDictionary() = default;
 
    explicit ObjectDictionary(
        std::initializer_list<std::pair<std::string_view, entry>>);
 
    uint32_t mapped_pdo_object(std::string_view name) const;
 
    uint16_t addr(std::string_view name) const;
 
    size_t size(std::string_view name) const;
 
    std::tuple<uint16_t, uint8_t, uint8_t> object(std::string_view name) const;
 
    static std::tuple<uint16_t, uint8_t, uint8_t>
    pdo_object_specs(uint32_t full_spec);
 
    void add_entry(std::string_view name, const DictionaryEntry& object);
 
    void add_entries(
        std::initializer_list<std::pair<std::string_view, entry>> entries);
 
private:
    const ObjectDictionary::DictionaryEntry&
    get_entry_safe(std::string_view name, std::string_view caller) const;
 
    std::map<uint64_t, DictionaryEntry> dictionary_;
};
 
using dico_t = ObjectDictionary;
 
class PDOMapping {
    ObjectDictionary* reference_dictionnary_;
    uint8_t index_;
    bool is_tx_;
    std::vector<std::pair<uint8_t, uint32_t>> objects_mapping_;
 
    void check_entry_throws(std::string_view obj) const;
 
public:
    using iterator = std::vector<std::pair<uint8_t, uint32_t>>::iterator;
    using const_iterator =
        std::vector<std::pair<uint8_t, uint32_t>>::const_iterator;
 
    PDOMapping(ObjectDictionary& dico, uint8_t idx, bool is_tx);
 
    PDOMapping(ObjectDictionary& dico, uint8_t idx, bool is_tx,
               std::initializer_list<std::string_view> objects);
 
    uint16_t map_addr() const;
 
    bool has_entry(std::string_view entry) const;
 
    const_iterator begin() const;
 
    const_iterator end() const;
 
    void reset();
 
    void add_object(std::string_view obj);
 
    bool configure(SlaveDevice& eth_slave) const;
 
    size_t memory_size() const;
 
    size_t memory_shift(std::string_view obj) const;
 
    template <typename T>
    bool check_buffer() {
        return memory_size() == sizeof(T);
    }
 
    bool check_entry_size(std::string_view obj, size_t bytes) const;
 
    bool is_tx() const;
 
    const ObjectDictionary& dictionary() const;
};
 
class PDOBuffer {
    std::vector<const PDOMapping*> mappings_;
    uint8_t* data_;
    bool is_tx_;
    uint16_t addr_;
    uint32_t flags_;
 
    void check_mapping_throws(const PDOMapping& mapping) const;
    void check_mapping_size_throws(const PDOMapping& mapping,
                                   size_t bytes) const;
 
    uint8_t* map_memory_internal(const PDOMapping& mapping, size_t bytes);
 
    const uint8_t* map_memory_internal(const PDOMapping& mapping,
                                       size_t bytes) const;
    const uint8_t* map_memory_internal(const PDOMapping& mapping,
                                       std::string_view entry_name,
                                       size_t bytes) const;
 
    uint8_t* map_memory_internal(const PDOMapping& mapping,
                                 std::string_view entry_name, size_t bytes);
 
    void check_entry_throws(const PDOMapping& mapping,
                            std::string_view entry_name, size_t bytes) const;
 
    size_t compute_shift(const PDOMapping& mapping,
                         std::string_view entry_name) const;
 
    const PDOMapping& access_mapping(size_t idx) const;
 
    template <typename T>
    std::tuple<T&> map_memory_tuple(size_t mapping_increment) {
        return std::tuple<T&>(map_memory<T>(access_mapping(mapping_increment)));
    }
 
    template <typename T, typename U, typename... Other>
    std::tuple<T&, U&, Other&...> map_memory_tuple(size_t mapping_increment) {
        return std::tuple_cat(
            map_memory_tuple<T>(mapping_increment),
            map_memory_tuple<U, Other...>(mapping_increment + 1));
    }
 
    template <typename T, typename U, typename... Other>
    std::tuple<const T&, const U&, const Other&...>
    map_memory_tuple(size_t mapping_increment) const {
        return std::tuple_cat(
            map_memory_tuple<T>(mapping_increment),
            map_memory_tuple<U, Other...>(mapping_increment + 1));
    }
 
    template <typename T>
    std::tuple<const T&> map_memory_tuple(size_t mapping_increment) const {
        return std::tuple<const T&>(
            map_memory<T>(access_mapping(mapping_increment)));
    }
 
public:
    PDOBuffer() = delete;
    PDOBuffer(bool is_tx, uint16_t addr_, uint32_t flags_);
 
    template <typename... T>
    PDOBuffer(bool is_tx, uint16_t addr, uint32_t flags, T&&... mappings)
        : PDOBuffer(is_tx, addr, flags) {
        add_mappings(std::forward<T>(mappings)...);
    }
 
    bool add_mapping(const PDOMapping& mapping, bool may_throw = false);
 
    template <typename... T>
    void add_mappings(T&&... mappings) {
        (add_mapping(std::forward<T>(mappings), true), ...);
    }
    void bind(uint8_t* data);
 
    bool contains_mapping(const PDOMapping& mapping) const;
 
    size_t mapping_memory_shift(const PDOMapping& mapping) const;
 
    size_t entry_memory_shift(const PDOMapping& mapping,
                              std::string_view entry) const;
 
    template <typename T>
    T& map_memory(const PDOMapping& mapping, std::string_view entry_name) {
        return *reinterpret_cast<T*>(
            map_memory_internal(mapping, entry_name, sizeof(T)));
    }
 
    template <typename T>
    const T& map_memory(const PDOMapping& mapping,
                        std::string_view entry_name) const {
        return *reinterpret_cast<const T*>(
            map_memory_internal(mapping, entry_name, sizeof(T)));
    }
 
    template <typename T>
    T& map_memory(const PDOMapping& mapping) {
        return *reinterpret_cast<T*>(map_memory_internal(mapping, sizeof(T)));
    }
 
    template <typename T>
    const T& map_memory(const PDOMapping& mapping) const {
        return *reinterpret_cast<const T*>(
            map_memory_internal(mapping, sizeof(T)));
    }
 
    template <typename T, typename U, typename... Other>
    std::tuple<T&, U&, Other&...> map_memory() {
        return map_memory_tuple<T, U, Other...>(0);
    }
 
    template <typename T, typename U, typename... Other>
    std::tuple<const T&, const U&, const Other&...> map_memory() const {
        return map_memory_tuple<T, U, Other...>(0);
    }
 
    template <typename T>
    T& map_memory() {
        return map_memory<T>(access_mapping(0));
    }
 
    template <typename T>
    const T& map_memory() const {
        return map_memory<T>(access_mapping(0));
    }
 
    uint16_t memory_size() const;
 
    void define_physical_buffer(SlaveDevice& eth_slave);
 
    bool configure(SlaveDevice& eth_slave) const;
 
    bool assign(SlaveDevice& eth_slave) const;
 
    void bind_physical_buffer(SlaveDevice& eth_slave);
};
 
using mapping_t = PDOMapping;
using buffer_t = PDOBuffer;
 
namespace cia402 {
 
// most useful conversion utilities
constexpr double rads2rpm = 60.0 / (2 * M_PI);
constexpr double rpm2rads = (2 * M_PI) / 60.0;
constexpr double rad2deg = 180. / M_PI;
constexpr double rev_to_rad = (2. * M_PI);
 
} // namespace cia402
 
} // namespace coe
} // namespace ethercatcpp