江端さんの技術メモ(04-19[長年日記])

2017-04-19 SOES: tutorial.txt ファイルリファレンス(翻訳途中)

SOES: tutorial.txt ファイルリファレンス

SOES v1.0.0

詳細説明

概要

SOESは、マイクロコントローラユーザアプリケーションに、以下のEtherCATフィールドバス通信環境を提供するライブラリです

EtherCAT 状態マシン
Mailbox インターフェース
プロトコル
- CoE
- FoE + ブートストラップテンプレート

メールボックスとプロトコルのサポートは、典型的なサンプルであり、あなたがEtherCATのアプリケーションレイヤをコントロールする為のスレーブスタックが必要となる時に役に立ちます。これらのアプリケーションで使用されるPDIは、SPIかいくつかのマイクロコントローラのインターフェースです。

以下は、どのようにSOESを立ち上げ起動させるかの幾つかの基本的なサンプルとなり、かつ、あなたがスレーブを設定するときの簡単なサンプルにもなります。全てのコードはアプリケーションの為のローカル変数またはグローバル変数で記述されています。必要なら修正や改良しても良いです。

ターゲットアプリケーションは以下の通りです

入力 40ビット
- 1ボタン 8ビット
- 1エンコーダ変数32ビット
出力 8ビット
- LED 8ビット
パラメータ
- エンコーダ設定
スレーブ命令
- リセットカウンター

SOESの上位での、翻訳または実装(？)

最初にスタートアップコードを見て下さい。このサンプルは、どのようにメイン関数を追加するかを示しており、スタートアップコードによって呼ばれることになります。このサンプルでは、mainの唯一の目的は、2つの新しいタスクを生み出すことです。一つはSOESを実行することで、もうひとつはエラーLEDをコントロールすることです。いくつかのESCは、エラーLEDの為のイベント用にRUN LED用のPINを提供しています。それがなければ、スレーブのマイクロコントローラから、それらをコントロールできます。以下SOESタスクに注力します。

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); }

構成

SOESの機能は、EtherCATスレーブデバイスであり、3つの部分に分割することができます。「ハードウェアの初期化」「ソフトウェア」「アプリケーションの初期化ループ」です。では、「ハードウェアの初期化」から説明します。

ハードウェアの初期化
- esc_resetは、物理的なEEPROMを使用しない場合に、ESCのために使用される特別リセットです。これは、一般的はESCハンドリングの一部ではなく、アプリケーションに固有のものです。
- ESC_init は、SPI通信等の初期化をします
- ESCが開始され、SPIが立ち上り動きだすのを待ち, ESCレジスタのDLステータスに問い合せします。if EEPROM loaded OK and PDI operational, eg. SPI OK.

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); ... }

ソフトウェア初期化
- ALステータスレジスタに書き込むことで、スレーブが初期化されます
- ALステータスコードレジスタに書き込むことで、エラーをクリアします
- アプリケーション層を停止し、データ交換を暗黙的にブロックするSyncManagersをディスエーブルします

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) ... }

アプリケーションループ
- ALeventハンドリング, ALイベントはALコントロールまたはSyncManagersの変化に関する情報を保持します。状態変化の為のALcontrolと、SyncManageは、EtherCATのアクティブSyncManagersにマッピングさたロれーカルメモリの中に書き込まれています。

ESC_state はステートをハンドリングします, 正常、エラー、または確認の応答で、ステートのアップダウンを行います

Mailbox handler, generic support of mailboxes used by all Application Layer protocols.

On mailbox actions we'll also check if we need to use a specific protocol handler to handle the incoming or outgoing Mailbox data.

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

Outputs
- Start by evaluating if we're in a state supporting update of outputs, eg. Operational state.
- If we're in OP we can read the current PDO data in the 3-buffer SyncManager mapped to the output SM, the default is SyncManager2, we read the ESC RAM address of SM2 and store it at the local address of the local variable Wb.LED. We'll read RXPDOsize bytes to trigger a complete SyncManager read.
- After local variables have been refreshed we basically write the local PDO variables to the User application, ex. a GPIO.
- Basically this is the API of the SOES toward the User Application.
- This function also include a watchdog mechanism, if triggered it will shutdown the outputs and trigger a state changes to safe operational. AlError is updated with cause of error to inform the Master.

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 (); } ... }

Inputs
- Is handled a bit simpler than outputs but in reverse order, the slave will continue update the inputs in state Safe Operational.
- Here we first read User application data from ex. GPIO and then write to local PDO variables.
- After the local variables have been refreshed we write those to the current PDO data 3-buffer SyncManager mapped to the input SM, the default is SyncManager3. This way we update the ESC RAM address with User Application data accessed by the EtherCAT master.

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.

Our target slave is Fixed PDO and OD

ESI-file

Snapshot from ESI tree from EtherCAT communication slides.

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.

0x0000 - 0x0FFF, Data Type Area
0x1000 - 0x1FFF, Communication Area
0x2000 - 0x5FFF, Manufacture specific area
0x6000 - 0x6FFF, Input area
0x7000 - 0x7FFF, Output area
0x8000 - 0x8FFF, Configuration area
0x9000 - 0x9FFF, Information area
0xA000 - 0xAFFF, Diagnosis Area
0xB000 - 0xBFFF, Service Transfer Area
0xC000 - 0xEFFF, Reserved Area
0xF000 - 0xFFFF, Device Area

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.

0, Unused
1, MailBox Receive, master to slave
2, MailBox Send, slave to master
3, Processdata output, master to slave
4, Processdata input, slave to master

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.

Type 3, Processdata output, master to slave

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

[ツッコミを入れる]