======================================
sdo - CANOpen SDO objects for MultiCAN
======================================

.. This text is RST (ReStructured Text),
   see also http://docutils.sourceforge.net/rst.html

Introduction
------------

The sdo protocol implements
`CANOpen <https://en.wikipedia.org/wiki/CANopen>`_
conform 
`sdo <https://www.can-cia.org/can-knowledge/sdo-protocol>`_
objects for MultiCAN.

Device Support
--------------

sdo currenty has device support for longin and longout records. 

To use sdo, set field ``DTYP`` to ``SDO``. 

The SDO object is specified in the link field ``INP`` or ``OUT``.
These are the properties that have to be specified:

+-----------------+----------------------+--------------------------------------+
|Property         | Value                | Meaning                              |
+=================+======================+======================================+
|Server-Flag      | "Server" or "Client" | Specifies if the IOC is a SDO        |
|                 |                      | server or a client                   |
+-----------------+----------------------+--------------------------------------+
|port             | an integer           | the port on the CAN bus card         |
+-----------------+----------------------+--------------------------------------+
|node             | an integer           | the CANOpen node number of the IOC   |
+-----------------+----------------------+--------------------------------------+
|index            | an integer           | the *index* of the SDO object        |
+-----------------+----------------------+--------------------------------------+
|subindex         | an integer           | the *subindex* of the SDO object     |
+-----------------+----------------------+--------------------------------------+
|datasize         | an integer           | the size of the data transferred in  |
|                 |                      | bytes                                |
+-----------------+----------------------+--------------------------------------+
|conversion-flag  | "integer" or "raw"   | specifies if an endianess conversion |
|                 |                      | is done ("integer") or the data is   |
|                 |                      | left unchanged ("raw")               |
+-----------------+----------------------+--------------------------------------+
|timeout          | an integer           | the timeout of the SDO object. If no |
|                 |                      | reply is received to an request in   |
|                 |                      | that time a MultiCAN timeout error   |
|                 |                      | is raised.                           |
+-----------------+----------------------+--------------------------------------+

Link specification
++++++++++++++++++

The link field string *must start* with a '@' character.

The link consists of a number of single character field specifiers followed by
a colon and a value. All fields have to be in the order shown below. None of
the fields may be omitted. Note that the address is given *either* in decimal
*or* in hexadecimal format, not both at the same time. These are the field
specifiers:

+---------------------+-----------+-------------------------------------------+
| name                | character | meaning                                   |
+=====================+===========+===========================================+
| client/server flag  | C         | specifies if the IOC is                   |
|                     |           | a SDO client or server                    |
+---------------------+-----------+-------------------------------------------+
| decimal address     | A         | specifies the SDO address information,    |
|                     |           | port and node number, index and subindex  |
+---------------------+-----------+-------------------------------------------+
| hexadecimal address | X         | specifies the hexadecimal SDO address     |
|                     |           | information, port and node number, index  |
|                     |           | and subindex                              |
+---------------------+-----------+-------------------------------------------+
| value specifier     | V         | specifies the value's size and type       |
+---------------------+-----------+-------------------------------------------+
| timeout specifier   | T         | specifies the timeout                     |
+---------------------+-----------+-------------------------------------------+

These are the values for the client/server flag:

+--------------------+
| client/server flag |
+-------+------------+
| value | meaning    |
+=======+============+
| S     | server     |
+-------+------------+
| C     | client     |
+-------+------------+

The address is specified by a list of 4 numbers which are separated just by commas, not spaces.
The elements of this list are:

+--------------------------------+
| address specification          |
+--------------------+-----------+
| number in the list | meaning   |
+====================+===========+
| 1                  | port      |
+--------------------+-----------+
| 2                  | node      |
+--------------------+-----------+
| 3                  | index     |
+--------------------+-----------+
| 4                  | subindex  |
+--------------------+-----------+

The value specifier ist consists of two comma separated values, a number, which is the datasize and a conversion flag. 

+----------------------------------------+
| value specification                    |
+---------------------+------------------+
| number in the list  | meaning          |
+=====================+==================+
| 1                   | size in bytes    |
+---------------------+------------------+
| 2                   | conversion flag  |
+---------------------+------------------+

These are the conversion flags known:

+-------------------------------------------+
| conversion flag                           |
+-------+-----------------------------------+
| value | meaning                           |
+=======+===================================+
| R     | raw, no re-ordering of the bytes  |
+-------+-----------------------------------+
| I     | integer, reorder bytes to CAN bus |
|       | byte order and back again         |
+-------+-----------------------------------+

Link specification examples
+++++++++++++++++++++++++++

Here is an example with a decimal address specification::

  @C:S A:8,127,32765,126 V:4,R T:50000

This link specifies a SDO server on port 8, node 127, index 32765 and subindex
126. The value has a size of 4 bytes and is of type raw. The timeout is 50000
milliseconds.

Here is another example with a hexadecimal address specification::

  @C:C X:2,6,1A02,A V:2,I T:3000

This link specifies a SDO client on port 2, node 6, index 6658 and subindex 10.
The value has a size of 2 bytes and is of type integer. The timeout is 3000
milliseconds.