@zimo-elektronik/zcan 1.0.0

package/protocol_docs/docs/command-groups/vehicles/vehicle-speed.md

@@ -0,0 +1,55 @@
+---
+id: vehicle-speed
+title: Vehicle Speed
+sidebar_position: 1
+---
+
+import CommandAndGroup from '@site/src/components/CommandAndGroup';
+
+<CommandAndGroup group="02" command="02"/>
+
+:::info
+
+East/West direction can't be changed with this command.
+It can be changed with [Vehicle special function switch](./vehicle-special-function-switch.md)
+
+:::
+
+## Receiving
+
+When receiving command _0x02_ the 'Data' section will look like this:
+
+| NID    | Speed and direction | Divisor |
+|--------|---------------------|---------|
+| 16 Bit | 16 Bit              | 8 Bit   |
+
+
+If Mode = 0b00, then the speed of the locomotive is requested with 'NID'. <br/> If M = 0b01, then the speed of the
+locomotive is set to the transferred value with 'NID'. <br/> If M = 0b11, then the locomotive responds with 'NID' to the
+request for its speed. <br/> Speeds are always sent with 10 Bit, in the upper 6 Bit additional Flags are sent. The
+respective conversion into rail format is done in the TSE. The 'Divisor' value indicates a shunting divisor (e.g.: /2 or
+/4) for a finer shunting resolution.
+
+### Speed and direction flags
+
+| Bit       | Description                                      | Value description                                |
+|-----------|--------------------------------------------------|--------------------------------------------------|
+| 0 ... 9   | Vehicle speed                                    |
+| 10        | Direction instruction (client to MX10)           | '0' ➔ Forward <br/> '1' ➔ Backward               |
+| 11        | Current track direction (MX10 to client)         | '0' ➔ Forward <br/> '1' ➔ Backward               |
+| 12 ... 13 | Sideways direction (Last direction from RailCom) | '0' ➔ Undefined <br/> '1' ➔ East<br/> '2' ➔ West |
+| 14        | Unused 🚧                                        |                                                  |
+| 15        | Vehicle Emergency Stop                           |                                                  |
+
+:::note
+For all track formats, the maximum ZIMO speed is 1008.  Values > 1008 are automatically set to 1008.
+:::
+
+## Sending
+
+When sending command _0x02_ the 'Data' section will look like this:
+
+| Vehicle address | Speed + direction | Value           |
+|-----------------|-------------------|-----------------|
+| 16 Bit          | 16 Bit            | 0x0000 - 16 Bit |
+

package/protocol_docs/docs/description.md

@@ -0,0 +1,4 @@
+---
+title: Descriptions
+sidebar_position: 300
+---

package/protocol_docs/docs/introduction/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Introduction",
+  "position": 0
+}

package/protocol_docs/docs/introduction/how-it-works.md

@@ -0,0 +1,61 @@
+---
+id: how-it-works
+title: How It Works
+sidebar_position: 1
+---
+
+## General structure of the message
+
+The command groups are structured in such a way that the respective CAN devices can use them as a filter criterion and thus do not have to evaluate all messages on the CAN bus.
+
+The use of the data bytes depends on the respective command. As far as reasonable, they are used in the following order:
+
+1. Destination ID Used when a specific device is to be addressed (e.g.: A turnout, a feedback device or a locomotive).
+2. Remaining data bytes These are used differently depending on the command; the exact use is listed with the individual commands.
+
+<table>
+  <thead>
+    <tr>
+      <th>ID Command Group</th>
+      <th>Counter</th>
+      <th>Data Byte 1</th>
+      <th>Data Byte 2</th>
+      <th>Data Byte 3</th>
+      <th>Data Byte 4</th>
+      <th>Data Byte 5</th>
+      <th>Data Byte 6</th>
+      <th>Data Byte 7</th>
+      <th>Data Byte 8</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>Command Group</td>
+      <td></td>
+      <td colspan="2">[Target ID]</td>
+      <td colspan="6">[More data after command]</td>
+    </tr>
+  </tbody>
+</table>
+
+## Basic ID structure:
+
+All 29 ID bits are shown in sequence, the **CAN** internal flags are not shown.
+
+| Bit 0 ... 15 | Bit 16 / 17 | Bit 18 ... 23 | Bit 24 ... 27 | Bit 28   |
+|--------------|-------------|---------------|---------------|----------|
+| 16           | 2           | 6             | 4             | 1        |
+| Network ID   | Mode        | Command       | Group         | Flag '1' |
+
+
+### Description of bit fields
+
+Field distribution for requests, commands, events and confirmations
+
+| Field     | Description                                                                                                      |
+|-----------|------------------------------------------------------------------------------------------------------------------|
+| Flag      | Always '1', serves to distinguish other protocols                                                                |
+| Group     | 4 bits for the respective command group. Indicates the respective Command Group (Sys, FeedBack, Loco, ...)       |
+| Cmd       | This 6 bit field contains the respective command                                                                 |
+| Mode      | 0b00: Request information <br/> 0b01: Control commands, Set values, etc. <br/> 0b10: Events <br/> 0b11: Response |
+| NetworkID | Identification number of the 'sender'. Primarily necessary to avoid collisions at the bus.                       |

package/protocol_docs/docs/introduction/implementation.md

@@ -0,0 +1,39 @@
+---
+id: implementation
+title: Implementation
+sidebar_position: 3
+---
+
+1. In principle, all commands are confirmed by 'ACKs', but this confirmation may take some time, depending on the command.
+2. A PC software MUST also process 'ACKs' for commands which it did not send itself. The MX10 always sends 'Command Acknowledgements' to all interfaces (physical CAN bus, XPressNet, PC interface).
+3. The computer software must be able to process the deviation data in "ACK". The computer software is responsible for this and must display the deviation data accordingly.
+4. A PC software must assume that it is not the only command source in the system, i.e: Control panels, possibly other programs or system-internal processes generate commands.
+5. The 'ACKs' always represent the MX10 internal state. This can deviate for various reasons from the desired state of a PC software for various reasons.
+6. The MX10 is designed for maximum data throughput. Commands with up to 1MBaud can be sent from the PC via the USB interface. PC can be sent. This corresponds to about 5000 to 15,000 commands per second (depending on the transmitted data bytes).
+7. All commands (CMDs) are immediately mapped by MX10 into the respective object (vehicle, switch, MX8, MX9, ...).
+8. Each object has its own asynchronously running state engine, which implements the desired target state.
+9. The object state engines process the commands with the respective possible speed. DCC commands need about 20mS until they reach a vehicle decoder for the first time. Commands to MX8 or MX9 modules in average only about 5mS.
+10. This means that MX8/MX9 commands can e.g.: Rail commands (vehicles, switches) can 'overtake'. The PC must therefore assume that it can receive an ACK for commands sent 'later'.
+11. Particular attention must be paid to the following in the case of vehicle commands: _If speed changes and function commands are sent to the same vehicle, the speed commands have priority over the function commands and are therefore processed first and also acknowledged._
+12. If speed commands are sent continuously over the interface, in a faster order than they can be sent to the track, then the 'most current' speed is always sent to the track. Intermediate jumps are ignored and thus skipped.
+13. The computer software must also assume that function commands are sent to the vehicle with a significant delay if the vehicle is simultaneously 'overloaded' with speed commands. In the worst case (because speed commands are present) only every 32nd command is used to send functions (so it may take 640 mS), for a full update of all functions (28) this means about 1.5 seconds!
+14. As noted above, each command is usually acknowledged by 'its' ACK, i.e., in essence, the corresponding command is 1:1 as an ACK with the corresponding 'ACTUAL' data. However, in some cases it is not possible. In the DCC format, functions are transferred to the vehicle in groups. Therefore ACK is also sent as a 'collective' ACK, which contains the status of all 32 functions.
+15. An application must send a message to the MX10 at least every 60 seconds, otherwise the connection is 'terminated' by the MX10. This is a protection for applications, which e.g.: 'crash', or leave the W-LAN range.
+
+## Optimal implementation for pc software
+
+For a PC software to use the possible interface throughput, it should implement the following:
+
+1. All commands sent by you should be stored in a list by the PC software (ring buffer).
+2. Commands which only change data (e.g.: speed) should not be entered in this list, but overwrite the already existing command.
+3. All "ACKs" from MX10 should be deleted from the list as 'done'.
+4. At the same time, it should be checked whether the 'confirmed' data (e.g.: speed) deviates from the own set-point.
+5. in case of deviation the software SHALL react sensibly, e.g. by sending:
+
+- Own set-point,
+- User Info,
+- Automatic adjustment of interlocking,
+- Speeds of other vehicles ... etc.
+
+6. ACKs which are not present in the list, i.e. which were not sent by the PC software, must be processed sensibly. In particular, 'ALL OFF', 'ALL STOP' must be observed here. But of course also travel commands and switching commands to vehicles.
+7. Depending on the type of command, PC software may assume that the ACK's require 500mS to 2000mS. Especially Rail commands can have considerable delays. If the PC software does NOT receive an ACK within this worst-case period, it must assume that an error has occurred.

package/protocol_docs/docs/introduction/interface.md

@@ -0,0 +1,62 @@
+---
+id: interface
+title: Interface
+sidebar_position: 2
+---
+
+## PC interface
+
+The connection to the PC can be made via Virtual (USB) Com-Port or Ethernet. In both cases the (CAN) protocol described here is used. Please note:
+
+1. Each command has a data length specification, this must be adhered to. The length ALWAYS refers to the user data, not to the header/tail or the command identification. (Size, Group, Cmd, Mode, ...).
+2. With a few exceptions, the protocol corresponds to the internally used CAN protocol. Therefore max. 8 data bytes are used.
+3. To optimize the communication with the PC, there are some commands (Group 0x10 ... 0x1F), which can transfer up to 256 data bytes.
+
+## PC USB interface
+
+The CAN data-grams are transferred between the ZIMO system USB interface and the PC using the following method
+
+### Establishing / initializing the connection
+
+If the PC wants to establish a connection, it must initialize the establishment by sending the string 'Z22Z' (=0x5A, 0x32, 0x32, 0x5A) to initialize the connection. Only after the MX10 has 'understood' such a string, it responds with a 'ping' telegram. a 'ping' telegram. If the ping fails for more than 500mS, the setup ring must be repeated. If there is no ping even after the third attempt, an error must be assumed.
+
+### Structure of the data telegrams for the zimo 2.x format for virtual com
+
+For the new CAN protocol the characters 'Z2' / '2Z' are used as telegram delimiter. In this case the CAN ID is transmitted field by field (Group, Direction, Command and NID).
+
+| Header | Size (DLC) | Group | Cmd + Mode | NID    | Data 0 ... 8 | CRC16  | Tail   |
+|--------|------------|-------|------------|--------|--------------|--------|--------|
+| 16 Bit | 8 Bit      | 8 Bit | 8 Bit      | 16 Bit | 8 x 8 Bit    | 16 Bit | 16 Bit |
+| 0x5A32 |            |       |            |        |              |        | 0x325A |
+
+
+CAN data-grams are essentially sent 1:1 within the frame defined above. However, since the USB (VCom) connection does not have a fixed limit of 8 data bytes, larger data-grams can be sent or received.
+
+:::note
+
+CRC16: When using a USB (Virtual COM Port) interface the value 0x0000 (CRC Ignore) can be used as CRC16. because the USB hardware already takes care for an error free transmission.
+
+:::
+
+## Ethernet/udp interface
+
+The Ethernet interface uses basically the same method for data transfer. The app layer data transfer is done in the Ethernet (LAN/W-LAN) via IP/UDP frames. A PC software (or App) sends its requests/commands via the UDP port 14520 to the MX10, the answers of the MX10 arrive at the PC, Tab, ... at port 14521.
+
+To initiate the connection the application must send a port 'Open' ([0x0A.0x06 or 0x1A.0x06]) to the MX10.
+
+:::note
+
+The ports can also be set to other values on the MX10, please refer to MX10 manual.
+
+:::
+
+### Structure of the data telegrams for the zimo 2.x format via udp
+
+For the data-gram transmission in the Ethernet no delimiters are necessary ('Z2' ... '2Z') because this is covered by the Ethernet frame logic. As with the USB (VCom) interface, the data is transferred 1:1 in the Ethernet as on the CAN bus. But there are some additional Ethernet data-grams, which can transfer much more data to the system. MX10 can send more data in one data-gram to the PC. These LAN special commands are listed separately.
+
+| Size (DLC) | Unused | Group | Cmd + Mode | NID    | Data 0 ... x |
+|------------|--------|-------|------------|--------|--------------|
+| 16 Bit     | 16 Bit | 8 Bit | 8 Bit      | 16 Bit |              |
+
+
+Since an Ethernet frame typically comprises 1536 bytes, the length specification has increased to 16 bits compared to the VCom interface. bit compared to the VCom interface. Additionally, there is a currently unused 16 bit field. This is intended for later extensions.

package/protocol_docs/docs/introduction/introduction.md

@@ -0,0 +1,82 @@
+---
+id: introduction
+title: Overview
+sidebar_position: 0
+---
+
+## Protocol
+
+The currently used ZIMO CAN protocol is now quite old (> 10 years) and has grown historically. It is therefore hardly possible to adapt this protocol to new requirements. For this reason, the devices of the Zs series (2010) will use a new extended protocol in parallel to the current CAN protocol (ZCAN10).
+
+The MX10 supports both protocols on its two CAN sockets. The CAN sockets labeled ZIMO use the 'old' protocol by default, while the sockets from other devices use the new CAN protocol. However, this can be changed in the MX10 menu at any time as required.
+
+## Layer 7
+
+So that a model railroad can actually be controlled, a layer-7 (application) must also be defined. The Layer-7 definition contains the definition of the 29Bit ID's and the 8 data bytes. So that such a CAN protocol works properly, it must be ensured that the 29Bit ID's of the CAN bus are unique system-wide.
+
+Practically all CAN controllers can mask and/or filter the CAN ID. By a CAN ID's it is possible to filter all CAN messages in such a way, that the respective device only has to process those messages which are really relevant. A turnout decoder for example does not get 'locomotive commands' at all. Conversely, a booster does not need to worry about 'switching commands'.
+
+## Addressing
+
+In the following, the term "object" is often used. By this term you can imagine any "addressable" thing on a model railway. In particular, it does not matter whether it is a vehicle, a switch or a USB key. All that matters is that such an object has a unique address (UID) in the active system and a few basic properties.
+
+Of course, specific objects have, in addition to their basic properties, "custom" properties that are valid only for this one object. For historical reasons, a distinction has to be made between "legacy objects" and ZCAN20 objects. Legacy Objects (DCC locomotive / turnout decoder, ...) do not have their own UIDs and their properties are mostly distributed in different CVs, or partially not available. ZCAN20 objects (but also ESU/Märklin) have a unique UID and also the necessary basic properties. In order to be able to use also common decoders and devices, there must be a management system that simulates the ZCAN20 objects to the rest of the system by means of computation, stored configurations, etc. In this way, even "legacy/conventional" decoders and other devices behave as ZCAN20 objects.
+
+## Translate Table For Legacy Devices:
+
+| UID Word1 | UID Word2 Min. | UID Word2 Max | Available Addresses |                                  |
+|-----------|----------------|---------------|---------------------|----------------------------------|
+| 0x0000    | 0x0000         | 0x27FF        | 10240               | DCC Locomotives                  |
+| 0x0000    | 0x2800         | 0x28FF        | 256                 | MM1/MM2 Locomotives              |
+| 0x0000    | 0x2900         | 0x2EFF        | 3072                | Available [1]                    |
+| 0x0000    | 0x2F00         | 0x2FFF        | 256                 | Multi-tractions                  |
+| 0x0000    | 0x3000         | 0x31FF        | 512                 | DCC 'Basic' Accessory Decoder    |
+| 0x0000    | 0x3200         | 0x39FF        | 2058                | DCC 'Extended' Accessory Decoder |
+| 0x0000    | 0x3A00         | 0x3DFF        | 1024                | MM1 Accessory Decoder            |
+| 0x0000    | 0x4000         | 0x43FF        | 1024                | S88 Feedback                     |
+| 0x0000    | 0x4400         | 0x45FF        | 1024                | X-Net Decoder                    |
+| 0x0000    | 0x4600         | 0x47FF        | 1024                | X-Net Feedback                   |
+| 0x0000    | 0x4800         | 0x4FFF        | 2048                | Available [2]                    |
+
+### ZIMO Device Generation 1
+| UID Word1 | UID Word2 Min. | UID Word2 Max | Available Addresses |                                          |
+|-----------|----------------|---------------|---------------------|------------------------------------------|
+| 0x0000    | 0x5000         | 0x503F        | 64                  | MX1                                      |
+| 0x0000    | 0x5040         | 0x507F        | 64                  | MX8 Module, Channel 1                    |
+| 0x0000    | 0x5080         | 0x50BF        | 64                  | MX9 Module, Channel 1                    |
+| 0x0000    | 0x50C0         | 0x50CF        | 16                  | CSA Module                               |
+| 0x0000    | 0x50D0         | 0x50DF        | 16                  | MX31                                     |
+| 0x0000    | 0x5100         | 0x513F        | 64                  | MX8 Module, Channel 2                    |
+| 0x0000    | 0x5140         | 0x517F        | 64                  | MX9 Module, Channel 2                    |
+| 0x0000    | 0x5800         | 0x5800        | 128                 | I2C eXtender, Differentiation see SubCmd |
+| 0x0000    | 0x5A00         | 0x5AFF        | 256                 | Block locations                          |
+
+
+### ZIMO System Database
+
+| UID Word2 Min. | UID Word2 Max                       | Available Addresses |                |
+|----------------|-------------------------------------|---------------------|----------------|
+| 0x6000         | 0x60FF  Panels / GBS / Signal boxes |
+| 0x6100         | 0x63FF                              | 768                 | Routes         |
+| 0x6400         | 0x65FF                              |                     |                |
+| 0x6600         | 0x66FF                              | 256                 | Sound Projects |
+| 0x6700         | 0x7FFF                              |                     | Reserved       |
+
+
+### Mfx Addresses
+
+| UID Word1 | UID Word2 Min. | UID Word2 Max | Available Addresses |                 |
+|-----------|----------------|---------------|---------------------|-----------------|
+| 0x0000    | 0x8000         | 0xBFFF        | 16384               | Mfx Locomotives |
+
+### ZIMO CAN 2.xx devices (Also from non ZIMO manufacturers)
+| UID Word2 Min. | UID Word2 Max | Available Addresses |                              |
+|----------------|---------------|---------------------|------------------------------|
+| 0xC000         | 0xC0FF        | 256                 | MX10 Central                 |
+| 0xC100         | 0xC1FF        | 256                 | MX10 Booster                 |
+| 0xC200         | 0xC2FF        | 256                 | Special equipment (IF, ....) |
+| 0xC300         | 0xC3FF        | 256                 | Driving consoles             |
+| 0xC400         | 0xC4FF        | 256                 | MX32 Radio modules           |
+| 0xD000         | 0xDFFF        | 4096                | Module                       |
+| 0xE000         | 0xEFFF        | 4096                | Object                       |
+| 0xF000         | 0xFFFF        | 4096                | Files                        |

package/protocol_docs/docusaurus.config.js

@@ -0,0 +1,111 @@
+// @ts-check
+// Note: type annotations allow type checking and IDEs autocompletion
+
+const lightCodeTheme = require('prism-react-renderer/themes/github');
+const darkCodeTheme = require('prism-react-renderer/themes/dracula');
+
+/** @type {import('@docusaurus/types').Config} */
+const config = {
+  title: 'ZCAN',
+  tagline: 'ZIMO CAN Bus Documentation',
+  url: 'https://your-docusaurus-test-site.com',
+  baseUrl: '/zcan',
+  onBrokenLinks: 'throw',
+  onBrokenMarkdownLinks: 'warn',
+  favicon: 'img/favicon.ico',
+
+  // GitHub pages deployment config.
+  // If you aren't using GitHub pages, you don't need these.
+  organizationName: 'Consultis', // Usually your GitHub org/user name.
+  projectName: 'zcan', // Usually your repo name.
+
+  // Even if you don't use internalization, you can use this field to set useful
+  // metadata like html lang. For example, if your site is Chinese, you may want
+  // to replace "en" with "zh-Hans".
+  i18n: {
+    defaultLocale: 'en',
+    locales: ['en'],
+  },
+
+  presets: [
+    [
+      'classic',
+      /** @type {import('@docusaurus/preset-classic').Options} */
+      ({
+        docs: {
+          sidebarPath: require.resolve('./sidebars.js'),
+          // Please change this to your repo.
+          // Remove this to remove the "edit this page" links.
+          editUrl: 'https://git.consultis.sk/Consultis/zcan',
+        },
+        blog: false,
+
+        theme: {
+          customCss: require.resolve('./src/css/custom.css'),
+        },
+      }),
+    ],
+  ],
+
+  themes: [
+    // ... Your other themes.
+    [
+      require.resolve('@easyops-cn/docusaurus-search-local'),
+      {
+        // ... Your options.
+        // `hashed` is recommended as long-term-cache of index file is possible.
+        hashed: true,
+        language: ['en'],
+        highlightSearchTermsOnTargetPage: true,
+        explicitSearchResultPath: true,
+        // For Docs using Chinese, The `language` is recommended to set to:
+        // ```
+        // language: ["en", "zh"],
+        // ```
+      },
+    ],
+  ],
+
+  themeConfig:
+    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
+    ({
+      navbar: {
+        title: 'ZCan',
+        // logo: {
+        //   alt: 'My Site Logo',
+        //   src: 'img/logo.svg',
+        // },
+        items: [
+          {
+            href: 'typedoc/index.html',
+            position: 'right',
+            label: 'API',
+            target: '_blank',
+            prependBaseUrlToHref: true,
+          },
+          {
+            type: 'doc',
+            docId: 'introduction/introduction',
+            position: 'right',
+            label: 'Protocol',
+          },
+          {
+            href: 'https://github.com/ZIMO-Elektronik/zcan',
+            label: 'GitHub',
+            position: 'right',
+          },
+        ],
+      },
+      footer: {
+        style: 'dark',
+
+        copyright: `Copyright © ${new Date().getFullYear()} ZCAN, Consultis k.s.`,
+      },
+      prism: {
+        theme: lightCodeTheme,
+        darkTheme: darkCodeTheme,
+      },
+    }),
+};
+
+module.exports = config;