SPI

Ingo

Preface

This documentation describes the process of creating an own SPI driver for CODESYS, based on the SPI Template, which can be found in the Code Repository. The driver consists of a "Device Description" as well as a CODESYS Library. All essential settings in the Library or the Device Description are repeated in this documentation. For more detailed informations about the Device Descriptions, please check the general I/O driver documentation.

Device Description

You can use a copy of the Device Description "SPI_Template.devdesc.xml" as a starting point. You need to adapt the following sections of the device description for your needs.

Device Identification

  • Set the Type to 501 for all SPI devices
<DeviceDescription>
  ...
  <Device>
    ...
    <DeviceIdentification>
      ...
      <Type>501</Type>
      ...
    </DeviceIdentification>
    ...
  </Device>
  ...
</DeviceDescription>
  • The ID consists of the "Vendor ID" (0003 for Open Source) and the "Device ID". As the Device ID needs to be unique, you have to register it in the Device Database.
<DeviceDescription>
  ...
  <Device>
    ...
    <DeviceIdentification>
      ...
      <Id>0003 0001</Id>
      ...
    </DeviceIdentification>
    ...
  </Device>
  ...
</DeviceDescription>
  • The version can be freely defined. Just, the format is fix. And you should take care that you never release two different device descriptions with the same Type, ID and Version. As this might produce conflicts in the repositories of other users.
<DeviceDescription>
  ...
  <Device>
    ...
    <DeviceIdentification>
      ...
      <Version>1.0.0.0</Version>
      ...
    </DeviceIdentification>
    ...
  </Device>
  ...
</DeviceDescription>

Connector

The connector describes the node in the device tree, which the user sees after he added your device. The I/O driver will search for this connector.

  • The moduleType is very important, that the I/O driver can find the corresponding device in the configuration. For SPI drivers, it has to be 500.
<DeviceDescription>
  ...
  <Device>
    ...
    <Connector moduleType="500" interface="Raspberry.SPI" ...>
      ...

      ...
    </Connector>
    ...
  </Device>
  ...
</DeviceDescription>
  • The interface has to be set to "Raspberry.SPI". Note, that currently only the Raspberry Pi is supported. When this limitation is removed, there will be another interface name.
<DeviceDescription>
  ...
  <Device>
    ...
    <Connector moduleType="500" interface="Raspberry.SPI" ...>
      ...

      ...
    </Connector>
    ...
  </Device>
  ...
</DeviceDescription>

Driver Info

This section specifies some parameters of the driver, and in our case, also which library should be used.

  • The RequiredLib tag specifies exactly which library has to be inserted to your project, when this driver is added to your device tree.
<DeviceDescription>
  ...
  <Device>
    ...
    <Connector moduleType="500" interface="Raspberry.SPI" ...>
      ...
      <DriverInfo needsBusCycle="false">
      ...
        <RequiredLib libname="SPI Template" vendor="Open Source" version="1.0.0.0" identifier="SPI Template">
        ...
        </RequiredLib>
        ...
        </Parameter>
      ...
    </Connector>
    ...
  </Device>
  ...
</DeviceDescription>
  • The FBInstance as well as its sub-tags defines which Function Block out of this library should be called.
    For an SPI driver all function calls from the template are important.
<DeviceDescription>
  ...
  <Device>
    ...
    <Connector moduleType="500" interface="Raspberry.SPI" ...>
      ...
      <DriverInfo needsBusCycle="false">
      ...
        <RequiredLib libname="SPI Template" vendor="Open Source" version="1.0.0.0" identifier="SPI Template">
        ...
          <FBInstance basename="$(DeviceName)" fbname="SPITemplate">
          ...
            <Initialize methodName="Initialize" />
            <CyclicCall methodname="AfterReadInputs" task="#buscycletask" whentocall="afterReadInputs" />
            <CyclicCall methodname="BeforeWriteOutputs" task="#buscycletask" whentocall="beforeWriteOutputs" />
          ...
          </FBInstance>
        ...
        </RequiredLib>
        ...
        </Parameter>
      ...
    </Connector>
    ...
  </Device>
  ...
</DeviceDescription>

Host Parameter Set

The host parameter set defines all your configuration parameters, as well as I/O channels. In the current SPI interface, you can use configuration parameters, but no I/O channels.

The configuration parameters can be read in the library within the function "Initialize".

<DeviceDescription>
  ...
  <Device>
    ...
    <Connector moduleType="500" interface="Raspberry.SPI" ...>
      ...
      <HostParameterSet>
      ...
        <Parameter ...>
        ...
        </Parameter>
      ...
    </Connector>
    ...
  </Device>
  ...
</DeviceDescription>

For more information about the HostParameterSet and datatypes, please check the general I/O driver documentation.