SOES v1.0.0
tutorial.txt File Reference

Detailed Description

General

The SOES is a library that provides the Micro Controller user application with the means to access the EtherCAT fieldbus communication environment:

Support for mailbox and protocols are typical examples when you need a slave stack to control the Application Layer of EtherCAT. The PDI used for such applications is either SPI or some Micro Controller Interface

The following sections show some basic examples on how to get the SOES up and running, as well as a lightweight example on howto design your slave. Since all code is local to the application or global variables, it is possible to tweak and optimize when possible.

Our target Application:

Now to translate and implement on top of SOES.

First look on the start up code. This example shows how to add a main function that will be called by startup code. In this example main's only purpose is to spawn two new tasks. One that executes SOES and one that control the ERROR LED. Some ESCs provided a pin for the RUN LED, some even for the ERROR LED, if it don't you can control them from the slave Micro Controller. We'll focus on the "soes" task.

int main (void)
{
   rprintp ("SOES (Simple Open EtherCAT Slave)\nsoes test\n");

   /* task_spawn ("led_run", led_error, 15, 512, NULL); /
   task_spawn ("led_error", led_error, 15, 512, NULL);
   task_spawn ("soes", soes, 9, 1024, NULL);

   return (0);
}

Configuration

The function soes is our EtherCAT slave device and can be split in 3 parts. Hardware Init, Software Init and Application loop. We will start with the Hardware Init.

void soes (void *arg)
{
   TXPDOsize = SM3_sml = sizeTXPDO ();
   RXPDOsize = SM2_sml = sizeRXPDO ();

   esc_reset ();
   ESC_init ((void *)spi_name);

   task_delay (tick_from_ms (200));

   // wait until ESC is started up
   while ((ESCvar.DLstatus & 0x0001) == 0)
   {
      ESC_read (ESCREG_DLSTATUS, (void *) &ESCvar.DLstatus,
                sizeof (ESCvar.DLstatus), (void *) &ESCvar.ALevent);
      ESCvar.DLstatus = etohs (ESCvar.DLstatus);
   }

   // reset ESC to init state
   ESC_ALstatus (ESCinit);
...
}

void soes (void *arg)
{
...
   while ((ESCvar.DLstatus & 0x0001) == 0)
   {
      ESC_read (ESCREG_DLSTATUS, (void *) &ESCvar.DLstatus,
                sizeof (ESCvar.DLstatus), (void *) &ESCvar.ALevent);
      ESCvar.DLstatus = etohs (ESCvar.DLstatus);
   }

   // reset ESC to init state
   ESC_ALstatus (ESCinit);
   ESC_ALerror (ALERR_NONE);
   ESC_stopmbx ();
   ESC_stopinput ();
   ESC_stopoutput ();

   // application run loop
   while (1)
...
}

Up until the now we're using the SOES protocol stack without any application specific calls. Next up we'll look at the application Code, here named DIG_process ().

void soes (void *arg)
{
...
   // application run loop
   while (1)
   {
      if((ESCvar.ALstatus & 0x0f) == ESCinit)
      {
         txpdomap = DEFAULTTXPDOMAP;
         rxpdomap = DEFAULTRXPDOMAP;
         txpdoitems = DEFAULTTXPDOITEMS;
         rxpdoitems = DEFAULTTXPDOITEMS;
      }
      ESC_read (ESCREG_LOCALTIME, (void *) &ESCvar.Time, sizeof (ESCvar.Time),
                (void *) &ESCvar.ALevent);
      ESCvar.Time = etohl (ESCvar.Time);

      ESC_ALevent();

      ESC_state ();
      if (ESC_mbxprocess ())
      {
         ESC_coeprocess ();
         ESC_foeprocess ();
         ESC_xoeprocess ();
      }
      DIG_process ();
   };
}

Application

The function DIG_process is the User part of the application and could be joined by more cyclic User functions for executing other parts of the application. The example code can be split in 2 parts

void RXPDO_update (void)
{
   ESC_read (SM2_sma, &Wb.LED, RXPDOsize, (void *) &ESCvar.ALevent);
}

void DIG_process (void)
{
   if (App.state & APPSTATE_OUTPUT)
   {
      if (ESCvar.ALevent & ESCREG_ALEVENT_SM2)  // SM2 trigger ?
      {
         RXPDO_update ();
         reset_wd ();
         gpio_set(GPIO_LED, Wb.LED & BIT(0));

      }
      if (!wd_cnt)
      {
         ESC_stopoutput ();
         // watchdog, invalid outputs
         ESC_ALerror (ALERR_WATCHDOG);
         // goto safe-op with error bit set
         ESC_ALstatus (ESCsafeop | ESCerror);
         wd_trigger = 1;
      }
   }
   else
   {
      reset_wd ();
   }
...
}

void TXPDO_update (void)
{
   ESC_write (SM3_sma, &Rb.button, TXPDOsize, (void *) &ESCvar.ALevent);
}

void DIG_process (void)
{
...
   Rb.button = gpio_get(GPIO_WAKEUP);
   Cb.reset_counter++;
   Rb.encoder =  Cb.reset_counter;

   TXPDO_update ();
}

ApplicationdataProcessdata

To run application data through EtherCAT processdata we need to describe for the fieldbus what data we have and will read/write. For this we have 3 objects, the ESI file, SII-EEPROM and CoE Object Dictionary. The first 2 are mandatory and the third is a very convenient way of describing complex slaves.

Our strategy is to keep the ESI file and the SII-EEPROM as thin as possible to avoid duplication of data that need to be maintained. Both will hold the bare minimum of mandatory + optional data to pass CTT. Optional data will be included to tell EtherCAT that detailed information can be retrieved via CoE from the OD stored in the slave it self.

SII-EEPROM

Snapshot from SII information matrix from EtherCAT communication slides.

sii_pdo.png
Our target slave is Fixed PDO and OD

ESI-file

Snapshot from ESI tree from EtherCAT communication slides.

esi_pdo.png
mandatory and optional ESI data

To briefly give a hint what are describe in the ESI and SII we're listing a set of included elements marked M for mandatory and O for optional.

 - Vendor (M) , Describes the identity.
  - Id (M), Hex, EtherCAT Vendor ID, OD 1018.01
  - Name (M), NameType, Expedient vendor name
 - Descriptions (M), Describes the EtherCAT device(s) using elements.
  - Groups (M), Similar devices can be assigned to one group. 
   - Group (M), One group groups similar devices with slightly different features
    - Type (M), A reference handle corresponding to the GroupType value in Description:Devices:Device:Group
   - Name (M), Name for this group show by a configuration tool
  - Devices (M), Element devices may describe one or several devices with their EtherCAT features such as SyncManagers, FMMUs and Dictionaries
   - Device (O), Holds all information about the device like syncmanagers and FMMU, object dictionary, data types and the PDO mapping and assign description
   - Device ATT: Physics (M),string, Physics at individual ports
    - Type (M), Device identity 
   - Type ATT:ProductCode="#x98123467" 
   - Type ATT:RevisionNo="#x00000001"
   - Name (M), Detailed name of device shown by a configuration tool (not used for identification)
    - GroupType (M), Reference to a group (described in element Groups) to which this device should be assigned to. Name of the handle used in element Groups:Group:Type         
    - Fmmu (O), String to describe function, Outputs -> RxPDO, Inputs -> TxPDO , MBoxState -> FMMU is used to poll Input Mailbox
   - Sm (O), Description of SyncManager including start address and direction. 
    - MBoxOut Mailbox Data Master -> Slave
    - MBoxIn Mailbox Data Slave -> Master
    - Outputs Process Data Master -> Slave
    - Inputs Process Data Slave -> master  
   - Sm ATT:DefaultSize="128" , Size
   - Sm ATT:StartAddress="#x1000" , Start address
   - Sm ATT:ControlByte="#x26" , Settings , Bit [1][0] = 10, Operation mode Mailbox, 00 Buffered 3.
   - Sm ATT:Enable="1", Enabled
   - Mailbox (O), Description of available mailbox protocols
   - Mailbox ATT: DataLinkLayer="true", Support of Mailbox Data Link Layer is mandatory.
    - CoE (O), Device support CoE
    - CoE (O) ATT: SdoInfo="true" , SDO Information Service 
    - CoE (O) ATT: CompleteAccess="false" , SDO complete access not supported
    - CoE (O) ATT: PdoUpload="true", PDO description uploaded from the slave's object dictionary and SyncManager length calculated based on the same
   - Dc (O), describes synchronization modes supported by the device.
    - OpMode (O), Definition of supported operation  modes
     - Name (M), Internal Handle of operation mode
     - Desc (O(M)), description of operation mode, recommended, Free Run (no sync), SM Synchronous, DC Synchronous 
     - AssignActive (M), Value of Latch and Sync Control registers
   - Eeprom (O, use is mandatory) 
    - Data (M)
         Or
    - ByteSize (M), Byte Size of connected EEPROM device
    - ConfigData (M), First 7 words of EEPROM, Configuration Areas
    - BootStrap (O), Start address and length of mailboxes for BootStrap

So to describe the application we use CoE and Object Dictionary. The mapping between Object Dictionary and the User Application are done via local variables defined as user types. The Object Dictionary itself is stored in a matrix where all the indexes are listed. Every index then have a submatrix with its subindex.

ObjectDictionary

The Object Dictionary used as example follow the CANopen DS301 ranges.

RxPDO , 0x1600 - 0x17FF TxPDO , 0x1A00 - 0x1BFF

Example, on how the the OD index are linked. Top index, SyncManagers Communication Types. In index 0 the 0x04 indicates we have 4 SyncManagers defined. Every SyncManager is assigned a type, in index 1-4, we have standard settings SM0 = 1, SM1 = 2, SM2 = 3, SM3 = 4 from ETG 1000.6, 5.6.7.4.

objectlist.h
FLASHSTORE _objectlist SDOobjects[] =
...
  {0x1C00, OTYPE_ARRAY, 4, 0, &acName1C00[0], &SDO1C00[0]},
  
FLASHSTORE _objd SDO1C00[] =
{ {0x00, DTYPE_UNSIGNED8, 8, ATYPE_R, &acNameNOE[0], 0x04, nil},
  {0x01, DTYPE_UNSIGNED8, 8, ATYPE_R, &acName1C00_01[0], 0x01, nil},
  {0x02, DTYPE_UNSIGNED8, 8, ATYPE_R, &acName1C00_02[0], 0x02, nil},
  {0x03, DTYPE_UNSIGNED8, 8, ATYPE_R, &acName1C00_03[0], 0x03, nil},
  {0x04, DTYPE_UNSIGNED8, 8, ATYPE_R, &acName1C00_04[0], 0x04, nil}

SyncManagers channels 0-31 are listed in SDO1C10-SDO1C2F. If we look at SyncManager channel 2, we see.

It got one RxPDO index 0x1600 connected, and the submatrix for 0x1600 link one PDO object index 0x7000 subindex 1. The output object 0x70000108 give you the index 0x7000, subindex 1 and PDO object length 1(byte).

objectlist.h
FLASHSTORE _objd SDO1C12[] =
{ {0x00, DTYPE_UNSIGNED8, 8, ATYPE_R, &acNameNOE[0], 0x01, nil},
  {0x01, DTYPE_UNSIGNED16, 16, ATYPE_R, &acNameMO[0], 0x1600, nil}
};
  
FLASHSTORE _objd SDO1600[] =
{ {0x00, DTYPE_UNSIGNED8, 8, ATYPE_R, &acNameNOE[0], 0x01, nil},
  {0x01, DTYPE_UNSIGNED32, 32, ATYPE_R, &acNameMO[0], 0x70000108, nil}
};

At PDO level we make the connection between the local application and the object dictionary. For all subindex in the PDO the last element is the address to the local variable.

objectlist.h
FLASHSTORE _objd SDO7000[] =
{ {0x00, DTYPE_UNSIGNED8, 8, ATYPE_R, &acNameNOE[0], 0x01, nil},
  {0x01, DTYPE_UNSIGNED8, 8, ATYPE_RW, &acName7000_01[0], 0, &(Wb.LED)}
};

utypes.h
typedef struct
{
   uint8 LED;
} _Wbuffer;

Beside SyncManager to PDO mapping we also have mandatory data as

0x1000 Device Type 0x1018 Object Identity 0x10C0 SyncManager Communication Type, as we used as top index when figuring out our PDOs in the Object Dictionary.

For a complete description of the object dictionary you can get guidance by the ETG1000.6 EcatAlProtocols

A useful feature is the Asynchronous use of SDO parameters. In the example we have Parameter set holding an encoder scale value, just for show we also have a read only mirror value of the encoder scale. Parameters defined as a RW SDO parameter and can be written/read by SDO Download or Upload. In addition there is a ESC_objecthandler Hook on SDO Download where you can add additional logic, ex. we execute the mirror of the encoder scale value by assigning the encoder scale value to the mirror.

objectlist.h
FLASHSTORE _objd SDO7100[] =
{ {0x00, DTYPE_UNSIGNED8, 8, ATYPE_R, &acNameNOE[0], 0x02, nil},
  {0x01, DTYPE_UNSIGNED32, 32, ATYPE_RW, &acName7100_01[0], 0, &(encoder_scale)},
  {0x02, DTYPE_UNSIGNED32, 32, ATYPE_R, &acName7100_02[0], 0, &(encoder_scale_mirror)}
};

soes.c
void ESC_objecthandler (uint16 index, uint8 subindex)
{
   switch (index)
   {
...
      case 0x7100:
      {
         switch (subindex)
         {
            case 0x01:
            {
               encoder_scale_mirror = encoder_scale;
               break;
            }
         }
         break;
      }
...
}

This tutorial is just one way of doing it. Enjoy and happy coding!

Andreas Karlsson, rt-labs AB, www.rt-labs.com

Generated on Wed Jul 10 2013 11:14:19 for SOES by  doxygen 1.7.4