DocumentationGenMarkup.cs

/*
    This file is part of libEDSsharp.

    libEDSsharp is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    libEDSsharp 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
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with libEDSsharp.  If not, see <http://www.gnu.org/licenses/>.

    Copyright(c) 2016 - 2019 Robin Cornelius <robin.cornelius@gmail.com>
    Copyright(c) 2020 Janez Paternoster
*/

using System;
using System.Collections.Generic;
using System.IO;
using System.Reflection;

namespace libEDSsharp
{
    /// <summary>
    /// Documentation generator
    /// </summary>
    public class DocumentationGenMarkup
    {
        StreamWriter file = null;

        /// <summary>
        /// Generate markup documentation
        /// </summary>
        /// <param name="filepath">where the documentation should be created</param>
        /// <param name="eds">data to generate the documentation from</param>
        public void genmddoc(string filepath, EDSsharp eds)
        {
            var versionAttributes = Assembly
                .GetExecutingAssembly()
                .GetCustomAttributes(typeof(AssemblyInformationalVersionAttribute), false)
                as AssemblyInformationalVersionAttribute[];

            string gitVersion = versionAttributes[0].InformationalVersion;
            file = new StreamWriter(filepath, false);
            file.NewLine = "\n";

            file.WriteLine(string.Format(
@"CANopen device documentation
============================
**{0}**

{1}

|              |                                |
| ------------ | ------------------------------ |
| Project File | {2,-30} |
| File Version | {3,-30} |
| Created      | {4,-30} |
| Created By   | {5,-30} |
| Modified     | {6,-30} |
| Modified By  | {7,-30} |

This file was automatically generated by [CANopenEditor](https://github.com/CANopenNode/CANopenEditor) {8}

[TOC]
",
            eds.di.ProductName, eds.fi.Description,
            Path.GetFileName(eds.projectFilename), eds.fi.FileVersion,
            eds.fi.CreationDateTime, eds.fi.CreatedBy, eds.fi.ModificationDateTime, eds.fi.ModifiedBy,
            gitVersion));

            file.WriteLine(string.Format(@"
Device Information
------------------
|              |                                |
| ------------ | ------------------------------ |
| Vendor Name  | {0,-30} |
| Vendor ID    | {1,-30} |
| Product Name | {2,-30} |
| Product ID   | {3,-30} |
| Granularity  | {4,-30} |
| RPDO count   | {5,-30} |
| TPDO count   | {6,-30} |
| LSS Slave    | {7,-30} |
| LSS Master   | {8,-30} |
| NG Slave     | {9,-30} |
| NG Master    | {10,-30} |
",          eds.di.VendorName, eds.di.VendorNumber, eds.di.ProductName, eds.di.ProductNumber,
            eds.di.Granularity, eds.di.NrOfRXPDO.ToString(), eds.di.NrOfTXPDO.ToString(),
            eds.di.LSS_Supported, eds.di.LSS_Master, eds.di.NG_Slave, eds.di.NG_Master));

            file.WriteLine($"#### Supported Baud rates");
            file.WriteLine($"* [{(eds.di.BaudRate_10 ? "x" : " ")}] 10 kBit/s");
            file.WriteLine($"* [{(eds.di.BaudRate_20 ? "x" : " ")}] 20 kBit/s");
            file.WriteLine($"* [{(eds.di.BaudRate_50 ? "x" : " ")}] 50 kBit/s");
            file.WriteLine($"* [{(eds.di.BaudRate_125 ? "x" : " ")}] 125 kBit/s");
            file.WriteLine($"* [{(eds.di.BaudRate_250 ? "x" : " ")}] 250 kBit/s");
            file.WriteLine($"* [{(eds.di.BaudRate_500 ? "x" : " ")}] 500 kBit/s");
            file.WriteLine($"* [{(eds.di.BaudRate_800 ? "x" : " ")}] 800 kBit/s");
            file.WriteLine($"* [{(eds.di.BaudRate_1000 ? "x" : " ")}] 1000 kBit/s");
            file.WriteLine($"* [{(eds.di.BaudRate_auto ? "x" : " ")}] auto");
            file.WriteLine();
            file.WriteLine();

            file.WriteLine("PDO Mapping");
            file.WriteLine("-----------");
            PrintPdoMd(eds);

            int chapter = 0;
            foreach (ODentry od in eds.ods.Values)
            {
                if (chapter == 0)
                {
                    file.WriteLine();
                    file.WriteLine("Communication Specific Parameters");
                    file.WriteLine("---------------------------------");
                    chapter++;
                }
                if (chapter == 1 && od.Index >= 0x2000)
                {
                    file.WriteLine();
                    file.WriteLine("Manufacturer Specific Parameters");
                    file.WriteLine("--------------------------------");
                    chapter++;
                }
                if (chapter == 2 && od.Index >= 0x6000)
                {
                    file.WriteLine();
                    file.WriteLine("Device Profile Specific Parameters");
                    file.WriteLine("----------------------------------");
                    chapter++;
                }

                if (!od.prop.CO_disabled)
                    PrintODentryMd(od);
            }

            file.Close();
        }
        /// <summary>
        /// Write a all PDO information in markup
        /// </summary>
        /// <param name="eds">data containing the information</param>
        /// <param name="skipDisabled">skip disabled PDOs</param>
        void PrintPdoMd(EDSsharp eds, bool skipDisabled = false)
        {
            var parameters = new SortedDictionary<UInt16, ODentry>();
            var mappings = new SortedDictionary<UInt16, ODentry>();
            foreach (ODentry od in eds.ods.Values)
            {
                if (od.Index < 0x1400 || od.prop.CO_disabled || od.objecttype != ObjectType.RECORD || od.subobjects.Count < 3)
                    continue;
                else if (od.Index < 0x1600)
                    parameters.Add(od.Index, od);
                else if (od.Index < 0x1800)
                    mappings.Add(od.Index, od);
                else if (od.Index < 0x1A00)
                    parameters.Add(od.Index, od);
                else if (od.Index < 0x1C00)
                    mappings.Add(od.Index, od);
                else
                    break;
            }

            foreach (ODentry par in parameters.Values)
            {
                UInt16 mappingIndex = (UInt16)(par.Index + 0x200);

                if (!mappings.ContainsKey(mappingIndex))
                    continue;

                ODentry map = mappings[mappingIndex];
                uint mapCount;

                // skip, if PDO (is disabled and) has no mapped entries
                try
                {
                    if (skipDisabled)
                    {
                        string cobId = par.subobjects[1].defaultvalue.Replace("$NODEID", "").Replace("+", "");
                        uint cobIdNum = (uint)new System.ComponentModel.UInt32Converter().ConvertFromString(cobId);
                        if ((cobIdNum & 0x80000000) != 0)
                            continue;
                    }
                    mapCount = (uint)new System.ComponentModel.UInt32Converter().ConvertFromString(map.subobjects[0].defaultvalue);
                    if (mapCount == 0)
                        continue;
                }
                catch (Exception)
                {
                    continue;
                }

                string transmissionType = $"type={par.subobjects[2].defaultvalue}";
                string PDO;

                if (par.Index < 0x1600)
                {
                    PDO = "RPDO";
                    if (par.subobjects.Count >= 6)
                        transmissionType += $"; event-timer={par.subobjects[5].defaultvalue}";
                }
                else
                {
                    PDO = "TPDO";
                    if (par.subobjects.Count >= 6)
                        transmissionType += $"; inhibit-time={par.subobjects[3].defaultvalue}; event-timer={par.subobjects[5].defaultvalue}";
                    if (par.subobjects.Count >= 7)
                        transmissionType += $"; SYNC-start-value={par.subobjects[6].defaultvalue}";
                }

                file.WriteLine(string.Format(@"
### {0} 0x{1:X4}
|              |                                                               |
| ------------ | ------------------------------------------------------------- |
| COB_ID       | {2,-62}|
| Transmission | {3,-62}|",
                    PDO, par.Index, par.subobjects[1].defaultvalue, transmissionType));

                for (byte subIdxPdo = 1; subIdxPdo <= mapCount; subIdxPdo++)
                {
                    UInt32 mapVal;
                    try { mapVal = (UInt32)new System.ComponentModel.UInt32Converter().ConvertFromString(map.subobjects[subIdxPdo].defaultvalue); }
                    catch (Exception) { break; }

                    UInt16 mapIdx = (UInt16)(mapVal >> 16);
                    UInt16 mapSub = (UInt16)((mapVal >> 8) & 0xFF);

                    string nameIdx = "(MISSING)";
                    string nameSub = " (MISSING)";
                    if (eds.ods.ContainsKey(mapIdx))
                    {
                        ODentry odMapped = eds.ods[mapIdx];
                        nameIdx = odMapped.parameter_name;

                        if (odMapped.objecttype == ObjectType.VAR)
                            nameSub = "";
                        else if (odMapped.subobjects.ContainsKey(mapSub))
                            nameSub = " (" + odMapped.subobjects[mapSub].parameter_name + ")";
                    }
                    else if (mapIdx < 0x20)
                    {
                        nameIdx = ((DataType)mapIdx).ToString();
                        nameSub = "";
                    }

                    file.WriteLine(string.Format(@"|   0x{0:X8} | {1,-62}|", mapVal, nameIdx + nameSub));
                }
                file.WriteLine();
            }
        }
        /// <summary>
        /// Write a object dictionary markup entry to file
        /// </summary>
        /// <param name="od">Object dictionary entry</param>
        void PrintODentryMd(ODentry od)
        {
            var descriptions = new List<string>();

            file.WriteLine(string.Format(@"
### 0x{0:X4} - {1}
| Object Type | Count Label    | Storage Group  |
| ----------- | -------------- | -------------- |
| {2,-12}| {3,-15}| {4,-15}|",
                 od.Index, od.parameter_name,
                 od.ObjectTypeString(), od.prop.CO_countLabel, od.prop.CO_storageGroup));

            if (od.Description != null && od.Description != "")
                descriptions.Add(od.Description);

            if (od.objecttype == ObjectType.VAR)
            {
                file.WriteLine(string.Format(@"
| Data Type               | SDO | PDO | SRDO | Default Value                   |
| ----------------------- | --- | --- | ---- | ------------------------------- |
| {0,-24}| {1,-4}| {2,-4}| {3,-5}| {4,-32}|",
                    PrintDataType(od), od.AccessSDO().ToString(), od.AccessPDO().ToString(),
                    od.prop.CO_accessSRDO.ToString(), od.defaultvalue));
            }
            else
            {
                file.WriteLine(string.Format(@"
| Sub  | Name                  | Data Type  | SDO | PDO | SRDO | Default Value |
| ---- | --------------------- | ---------- | --- | --- | ---- | ------------- |"));

                foreach (ODentry subod in od.subobjects.Values)
                {
                    file.WriteLine(string.Format(@"| 0x{0:X2} | {1,-22}| {2,-11}| {3,-4}| {4,-4}| {5,-5}| {6,-14}|",
                        subod.Subindex, subod.parameter_name, PrintDataType(subod),
                        subod.AccessSDO().ToString(), subod.AccessPDO().ToString(),
                        subod.prop.CO_accessSRDO.ToString(), subod.defaultvalue));

                    if (subod.Description != null && subod.Description != "")
                        descriptions.Add(subod.Description);
                }
            }

            if (descriptions.Count > 0)
            {
                file.WriteLine();
                file.WriteLine(string.Join("\n", descriptions));
            }
        }
        /// <summary>
        /// Returns the datatype of a object dictionary
        /// </summary>
        /// <param name="od">the object dictionary entry</param>
        /// <returns>datatype of the OD entry</returns>
        string PrintDataType(ODentry od)
        {
            string dt = od.datatype.ToString();
            if ((od.datatype == DataType.VISIBLE_STRING || od.datatype == DataType.UNICODE_STRING)
                && od.prop.CO_stringLengthMin > od.defaultvalue.Length)
            {
                dt += $" (len={od.prop.CO_stringLengthMin})";
            }

            return dt;
        }
    }
}