rapidm2m-c3xx-base

Abstract:

This library provides functions for the different interfaces of the rapidM2M C3xx device. The library supports both rapidM2M C33x and rapidM2M C32x devices. In order for your rapidM2M C3xx to be supported by this library correctly you must select the rapidM2M hardware platform installed in your rapidM2M C3xx via the drop-down list "Device profile" in the "Project settings" (e.g. rapidM2M M2 in the case of a rapidM2M C32x, rapidM2M M23 in the case of a rapidM2M C33x).

Supported rapidM2M devices:

rapidM2M C32x (based on rapidM2M M22x hardware platform):
- Firmware: 01v026 and higher
rapidM2M C33x (based on rapidM2M M23x hardware platform):
- Firmware: 01v016 and higher

If you use this library in your IoT app, you should specify the minimum required version of the firmware under "required HW & FW" in the project settings.

Most of the IO processing functionalities (UI, RS232, RS485, CAN, Digout) will be executed on an internal co-processor (IOController). The IOController is connected with the rapidM2M M2xx module inside the rapidM2M C3xx. through UART and SPI interface. The UART interface will be used for simple command handling (ASCII), the SPI interface if data has to be transferred (BINARY). The low-level interface access functions will be hidden from the user through higher-level API functions (e.g. IOCtrl_UI_Init).

The number of IOs can be increased by connecting IO Extension modules (e.g. rapidM2M C3e 12UI/2Rel for additional inputs or rapidM2M C3e 3mA/6Rel for additional outputs). These modules will be connected via CAN interface to the rapidM2M C3xx. See chapter IO Extension for more information.

Config:

rapidM2M C3xx

To enable the rapidM2M C3xx library, add the following macro to the main.dde file.

This macro must be defined in order to use the library.

/** ---------------------------------------------------------------------------- * rapidm2m-c3xx-base: rapidM2M C3xx Config * ----------------------------------------------------------------------------- * * Use this macro to enable the callback functions for the features (provided by the IO Controller) which you want to use: * * -1: disables the specific feature to save memory * This value is currently only supported for IOCTRL_RS232, IOCTRL_RS485 and IOCTRL_CAN * 0: disables all callback functions for a specific feature * 1: only enables the essential callback functions for a specific feature * 2: enables all callback functions for a specific feature */ #define IOCTRL_COMMON 0 // Generell Information regarding the IO Controller #define IOCTRL_UI 0 // Universal inputs #define IOCTRL_RS232 0 // RS232 Interface #define IOCTRL_RS485 0 // RS485 Interface #define IOCTRL_CAN 0 // CAN Interface #define IOCTRL_DIGOUT 0 // Digital Outputs #define IOCTRL_SHUTDOWN 0 // Shutdown Handling

Generell information regarding the IO Controller

IOCTRL_COMMON >= 1

IOCtrl_ReadyCallback

IOCtrl_SysValuesCallback

IOCTRL_COMMON >= 2

IOCtrl_IdCallback

IOCtrl_FwInfoCallback

IOCtrl_UpdateCallback

Universal inputs

IOCTRL_UI >= 1

IOCtrl_UIValueCallback

IOCTRL_UI >= 2

IOCtrl_UIInitCallback

IOCtrl_UITriggerInitCallback

IOCtrl_UIGetLastDigitalCallback

IOCtrl_UIResetCounterCallback

RS232 interface

IOCTRL_RS232 = -1

RS232 feature disabled (save memory)

IOCTRL_RS232 >= 1

IOCtrl_RS232RxCallback

IOCTRL_RS232 >= 2

IOCtrl_RS232InitCallback

IOCtrl_RS232WriteCallback

RS485 interface

IOCTRL_RS485 = -1

RS485 feature disabled (save memory)

IOCTRL_RS485 >= 1

IOCtrl_RS485RxCallback

IOCTRL_RS485 >= 2

IOCtrl_RS485InitCallback

IOCtrl_RS485WriteCallback

CAN interface

IOCTRL_CAN = -1

CAN feature disabled (save memory). Using IO Extensions is still possible.

IOCTRL_CAN >= 1

IOCtrl_CANRxCallback

IOCTRL_CAN >= 2

IOCtrl_CANInitCallback

IOCtrl_CANWriteCallback

IOCtrl_CANGetStatCallback

Digital outputs

IOCTRL_DIGOUT >= 2

IOCtrl_DigOutInitCallback

IOCtrl_DigOutSetValueCallback

Shutdown handling

IOCTRL_SHUTDOWN >= 1

IOCtrl_BackupSupplyOnCallback

IOCtrl_BackupSupplyOffCallback

IOCtrl_OutageTimeoutExpCallback

C3 IO Extension Modules

To enable the C3 IO extension module library features, add the following macro to the main.dde file.

The following macro needs to be defined to use the IO Extension modules.

/** ---------------------------------------------------------------------------- * rapidm2m-c3xx-base: C3 IO Extension Modules Config * ----------------------------------------------------------------------------- * * Use this macro to enable the callback functions for the features (provided by the IO Extension) which you want to use: * * 0: disables all callback functions for a specific feature * 1: only enables the essential callback functions for a specific feature * 2: enables all callback functions for a specific feature */ #define IOEXT_COMMON 0 // Generell Information regarding the IO Extensions #define IOEXT_UI 0 // Universal inputs (only for C3e 12UI/2Rel) #define IOEXT_DIGOUT 0 // Digital Outputs #define IOEXT_AO 0 // Analog Outputs (only for C3e 3mA/6Rel)

Generell information regarding the IO Extensions

IOEXT_COMMON >= 1

IOExt_ReadyCallback

IOEXT_COMMON >= 2

IOExt_ErrorCallback

IOExt_SysValuesCallback

IOExt_UpdateCallback

IOExt_IDCallback

IOExt_FwInfoCallback

IOExt_StateCallback

Universal inputs (only for C3e 12UI/2Rel)

IOEXT_UI >= 1

IOExt_UIValueCallback

IOEXT_UI >= 2

IOExt_UIInitCallback

IOExt_UIGetLastDigitalCallback

IOExt_UIResetCounterCallback

Digital outputs

IOEXT_DIGOUT >= 2

IOExt_DigOutInitCallback

IOExt_DigOutSetValueCallback

Analog outputs (only for C3e 3mA/6Rel)

IOEXT_AO >= 2

IOExt_AOInitCallback

IOExt_AOSetValueCallback

IOExt_AOGetStatCallback

Init:

The IOController must be enabled by the M2M module. This is carried out by C3_Init function that must be called prior to any other libary functions.

C3_Init()

After calling C3_Init is is necessary to wait until IOController is responding (indicated through callback function IOCtrl_ReadyCallback).

Shutdown:

In the event of a supply voltage failure the supply is switched to the rechargeable buffer battery. This is done as soon as the supply voltage falls below 8,65V. The switch to the rechargeable buffer battery is detected by this library and the shutdown handling procedure is started.

IOCTRL_SHUTDOWN (see Config) can be used to enable the Shutdown Handling callbacks:

IOCTRL_SHUTDOWN = 0 - Disables all Shutdown Handling callbacks

IOCTRL_SHUTDOWN = 1 - Shutdown handling callbacks are enabled

Shutdown Handling procedure:

The callbacks mentioned below are only called if IOCTRL_SHUTDOWN is set to 1.

For certain events, applog entries (see Constants_for_Shutdown_Handling) are generated if "C3_BASE_APPLOG" is set to 1 (default, see Advanced_Config)

When the supply is switched to the rechargeable buffer battery IOCtrl_BackupSupplyOnCallback() is called to indicate that a supply voltage failure was detected and the applog entry "MT_BACKUPSUPPLY, MT_BACKUPSUPPLY_BATTERY_ACTIVE" is generated.
The outage timeout is started (use C3_SetShutdownTimeouts() to configure the timeout)
If the outage timeout expires the IOCtrl_OutageTimeoutExpCallback() is called and the applog entry "MT_BACKUPSUPPLY, MT_BACKUPSUPPLY_OUTAGE_EXPIRED" is generated.

If the outage timeout has expired, it is recommended to generate an alarm/warning (using Alerts_CheckAlarm_f32() function of the "alerts-microtronics" libary) and trigger a uplink synchronization (using uplinkFlush()) to inform the server about the supply voltage failure.

After that the shutdown timeout is started (use C3_SetShutdownTimeouts() to configure the timeout). During this phase it is recommended to terminate a possibly active connection and shutdown down the rapidM2M C3xx by calling C3_TriggerShutdown() which generates the applog entry "MT_SHUTDOWN".
If the shutdown timeout has also expired (i.e. C3_TriggerShutdown() has not been called), the library switches the uplink mode to "UPLINK_TRIG" and waits until a possibly active connection is terminated or a fixed timeout of 120 seconds is expired.
Finally the library closes all interfaces (CAN, RS232 and RS485) and shuts down the rapidM2M C3xx.

If the supply voltage increases to above 8,65V again during one of the steps described above the shutdown procedure is stopped. IOCtrl_BackupSupplyOffCallback() is called and the applog entry "MT_BACKUPSUPPLY, MT_BACKUPSUPPLY_EXT_SUPPLY_ACT" is generated to indicate that the supply voltage is available again and the rechargeable buffer battery has been disabled. If the supply voltage recovers during step 5 of the shutdown procedure the library automatically switches back to the uplink mode that was set before the switch to "UPLINK_TRIG".

Advanced_Config:

The settings mentioned in this chapter should only be changed if really required (e.g. memory saving required). To adapt the settings add the following block to the main.dde file.

/** ---------------------------------------------------------------------------- * rapidm2m-c3xx-base: Advanced Config * ----------------------------------------------------------------------------- * * Use this block to adapt the advanced configuration settings: * */ #define IOCTRL_RS232_TXLEN 256 // TX-Buffer size for RS232 interface #define IOCTRL_RS232_RXLEN 256 // RX-Buffer size for RS232 interface #define IOCTRL_RS485_TXLEN 256 // TX-Buffer size for RS485 interface #define IOCTRL_RS485_RXLEN 256 // RX-Buffer size for RS485 interface #define IOCTRL_CAN_TX_MSG 32 // Number of entries within CAN TX Message Buffer #define IOCTRL_LEN_CMD_QUEUE 20 // Number of Command Queue Entries for IO Controller Communication #define IOCTRL_N_CMDSEQ 1 // Number of command sequence buffers #define IOCTRL_CMDSEQ_DATA_LEN 4096 // Size of every command sequence buffer /** ---------------------------------------------------------------------------- * Use this block to configure the library's applog function: * * 0: Disable generation of applog entries * 1: Enable generation of applog entries (default) */ #define C3_BASE_APPLOG 1

TC3_Cfg:

global C3 configuration structure

FTIdUpdate : s32 - Filetransfer ID for IOController Update

IOCTRL_LEN_CMD_QUEUE -

Number of Command Queue Entries for IO Controller Communication

20 (Default)

It is only possible to send one command to the IO Controller at a time. A queue with this size is used to buffer pending commands.

IOCTRL_ID_BOARD_MAXLEN -

20

IOCTRL_ID_MODULE_MAXLEN -

20

TIOCtrl_Id:

IO Controller Identification Structure

board{IOCTRL_ID_BOARD_MAXLEN+1} : str - Board Name

Used to identify the installed Firmware. Default: "C3"

module{IOCTRL_ID_MODULE_MAXLEN+1} : str - Module Name

Used to identify the installed Firmware. Default: "IOController" for the rapidM2M C3xx and "IOExtension" for rapidM2M C3e IO extension modules.

hwmajor : u8 - HW Version Major

hwminor : u16 - HW Version Minor

Example HW-Version String: "02v001" (major=2, minor=1)

fwmajor : u8 - FW Version Major

fwminor : u16 - FW Version Minor

Example FW-Version String: "03v002" (major=3, minor=2)

serial : u32 - Serial Number

Example Serial Number String: "MT-02398674" (serial=2398674)

numUI : u8 - Number of UI channels

numDIGOUT : u8 - Number of DIGOUT channels

numAO_mA : u8 - Number of mA analog output channels

C3_STATE_x:

Possible C3xx states

Shutdown handling procedure

C3_STATE_BACKUP_OUTAGE_TIMEOUT = 1 - Supply voltage failure was detected and therefore the outage timeout was started. The supply has been switched to the rechargeable buffer battery.

During the outage timeout no specific shutdown measures are taken by the rapidm2m-c3xx-base library. But the following components fail as soon as the rapidM2M C3xx is only supplied by the rechargeable buffer battery:

CAN (As a result also any communication with IO Extensions is not possible any more)

5V supply voltage at pin 9 of the RS232 interface

Relays

C3_STATE_BACKUP_SHTDWN_TIMEOUT = 2 - Outage timeout has expired and the shutdown timeout was started. This state is entered after IOCtrl_OutageTimeoutExpCallback() is called. If the shutdown timeout has also expired the library closes all interfaces (CAN, RS232 and RS485) and shuts down the rapidM2M C3xx.

IOCtrl_ReadyCallback(res, sId[TIOCtrl_Id]=[0])

IO Controller Ready (Callback for C3_Init())

res - OK if successful, otherwise ERROR (IO Controller not responding)

sId[TIOCtrl_Id] - IO Controller ID information

Function is called if IO Controller was responding after calling C3_Init or if IO Controller unsolicited restart was detected (probably caused by IO Controller Firmware Exception).

C3_Init(sC3_Cfg[TC3_Cfg]=[0])

initializes C3 Base Library

sC3Cfg : TC3_Cfg - Optional C3 configuration

returns : s32 - Resultcode

OK - If command was accepted

C3_ERROR_INIT_ALREADY_TRIGGERED - see C3_ERROR_x

C3_ERROR_INIT_ALREADY_DONE - see C3_ERROR_x

ERROR - If one of the following error occurs

UART init failed

SPI init failed

Timer init failed

IOCtrl_GetId()

Read IO Controller Firmware Identification

returns : s32 - OK if command was accepted, otherwise ERROR

Function works non-blocking. Function IOCtrl_IdCallback will be called if ID information is available.

IOCtrl_IdCallback(sId[TIOCtrl_Id])

IO Controller ID information is available (Callback for IOCtrl_GetId())

sId[TIOCtrl_Id] - IO Controller ID information

IOCtrl_SetDebugPort(port)

Set IO Controller Debug Output Port.

port - see IOCTRL_DEBUG_PORT definitions

returns : s32

OK - Command accepted

ERROR - If one of the following errors occurs

IO controller command is currently not allowed (init, reset, shutdown or update is in progress).

Command queue is full.

IOCtrl_Shutdown()

Force IO Controller Shutdown.

returns : s32

OK - Command accepted

ERROR - If one of the following errors occurs

IO controller command is currently not allowed (init, reset, shutdown or update is in progress).

Command queue is full.

Function works non-blocking. The IO Controller Firmware will perform all closing tasks required for safe power off.

IOCTRL_FLG:

IO Controller System Value Flags (Bitmask)

IOCTRL_FLG_BACKUP_ACTIVE - Backup Supply (Battery) active (0x01)

Backup Supply is automatically activated, if input supply is not available. It is recommended to perform 'Input Supply missing' alarm/warning handling and shutdown through function C3_TriggerShutdown() afterwards.

IOCTRL_RST:

IO Controller Reset Cause enumerator

IOCTRL_RST_UNKNOWN - -1

IOCTRL_RST_PORST - 0 (Power on reset)

IOCTRL_RST_BORST - 1 (Brown out reset)

IOCTRL_RST_EXTRST - 2 (External reset)

IOCTRL_RST_SWRST - 3 (Software reset)

IOCTRL_RST_WDOGRST - 4 (Watchdog reset)

IOCTRL_RST_LPRST - 5 (Low-power management reset)

IOCTRL_RST_PDRST - 6 (Power Domain (1 or 2) reset)

IOCTRL_EXCEPT:

IO Controller Exception Causes

IOCTRL_EXCEPT_NONE - 0

IOCTRL_EXCEPT_NMI - 1

IOCTRL_EXCEPT_HARD_FAULT - 2

IOCTRL_EXCEPT_MEM_MANAGE - 3

IOCTRL_EXCEPT_WDOG_TIMEOUT - 4

IOCTRL_EXCEPT_BUS_FAULT - 5

IOCTRL_EXCEPT_USAGE_FAULT - 6

IOCTRL_EXCEPT_SVC - 7

IOCTRL_EXCEPT_DEBUG_MON - 8

IOCTRL_EXCEPT_PEND_SV - 9

IOCTRL_EXCEPT_SYS_TICK - 10

IOCTRL_EXCEPT_UNHANDLED_IRQ0 - 11

IOCTRL_EXCEPT_UNHANDLED_IRQ15 - 26

EXCEPT_DMA_ERROR - 27

C3_ERROR_x:

C3xx Error Codes

Firmware Update Errors

These error codes are only present on an IO Controller FW >= 01v006 and in case IOCtrl_EnableDowngrade() or IOExt_EnableDowngrade() are not called before a FW update.

C3_ERROR_FW_OLD_VERSION = (-2) - Firmware downgrade not allowed

C3_ERROR_FW_SAME_VERSION = (-3) - Firmware update with the same version not allowed

IO Controller Init Errors

C3_ERROR_INIT_ALREADY_TRIGGERED = (-4) - C3_Init() has already been called

C3_ERROR_INIT_ALREADY_DONE = (-5) - C3_Init() has already been called and the IOCtrl_ReadyCallback() reported that the IO controller is ready.

Shutdown Handling Errors

C3_ERROR_BACKUP_OUTAGE_TIMEOUT = (-6) - C3_SetShutdownTimeouts() invalid outage timeout supplied

C3_ERROR_BACKUP_SHTDWN_TIMEOUT = (-7) - C3_SetShutdownTimeouts() invalid shutdown timeout supplied

TIOCtrl_SysValue:

IO Controller System Values

Flags - see IOCTRL_FLG definitions

VIn - Input Voltage [mV]

ResetCause - Cause for last IO Controller Reset, see IOCTRL_RST definition

ExceptCause - Last IO Controller Exception: Cause (see IOCTRL_EXCEPT definitions)

ExceptPC - Last IO Controller Exception: Address (Program Counter Value)

ExceptLR - Last IO Controller Exception: Link Register Value

ExceptR0 - Last IO Controller Exception: R0 Register Value

TIOExt_SysValue:

IO Extension System Values

VIn - Input Voltage [mV]

ResetCause - Cause for last Reset, see IOCTRL_RST definitions

ExceptCause - Last Exception: Cause (see IOCTRL_EXCEPT definitions)

ExceptPC - Last Exception: Address (Program Counter Value)

ExceptLR - Last Exception: Link Register Value

ExceptR0 - Last Exception: R0 Register Value

IOCtrl_GetSysValues(extSerial=-1)

Read IO Controller System Values.

extSerial - serial number of the extension module, -1 if not used

returns : s32

OK - Command accepted

ERROR - If one of the following errors occurs

IOCtrl_SysValuesCallback/IOExt_SysValuesCallback not activated. Check your Library Config.

IO controller command is currently not allowed (init, reset, shutdown or update is in progress).

Command queue is full.

Command sequence is full.

Function works non-blocking. Function IOCtrl_SysValuesCallback will be called if System Values for the rapidM2M C3xx are available (extSerial = -1). Function IOExt_SysValuesCallback will be called if System Values for C3 extension module are available (extSerial >= 0).

Command may be used within a command sequence. See Command Sequence Usage for more information.

IOCtrl_SysValuesCallback(sSysValues[TIOCtrl_SysValue])

IO Controller System Values are available (Callback for IOCtrl_GetSysValues() )

sSysValues[TIOCtrl_SysValue] - IO Controller System Values

IOExt_SysValuesCallback(serial, sSysValues[TIOExt_SysValue])

IO Extension System Values are available (Callback for IOCtrl_GetSysValues() )

serial - serial number of the extension module

sSysValues[TIOExt_SysValue] - IO Extension System Values

IOCTRL_FWINFO_ID -

"C3 IOController"

Firmware identification string for the default IO Controller firmware

IOEXT_FWINFO_ID -

"C3 IOExtension"

Firmware identification string for the default IO Extension firmware

TIOCtrl_FwInfo:

Firmware information structure

szId{32} : str - Firmware Identification String (IOCTRL_FWINFO_ID, IOEXT_FWINFO_ID)

fwmajor : u8 - FW Version Major

fwminor : u8 - FW Version Minor

Example FW-Version String: "03v002" (major=3, minor=2)

size : u32 - Firmware Size (number of bytes)

crc : u32 - Firmware CRC

IOCtrl_GetFwInfo()

Read Firmware Info

returns : s32

OK - Command accepted

ERROR - If one of the following errors occurs

IOCtrl_FwInfoCallback not activated. Check your Library Config.

IO controller command is currently not allowed (init, reset, shutdown or update is in progress).

Command queue is full.

Command sequence is full.

This function provides the information for the firmware that is currently active. Function works non-blocking. Firmware information will be passed to the function IOCtrl_FwInfoCallback.

Command may be used within a command sequence. See Command Sequence Usage for more information.

IOCtrl_FwInfoCallback(sInfo[TIOCtrl_FwInfo])

Firmware information is available (Callback for IOCtrl_GetFwInfo() )

sInfo - Firmware Information

IOCtrl_EnableDowngrade()

Enable IO Controller firmware downgrades

This function will automatically call IOCtrl_Update() after enabling downgrades!

returns : s32

OK - Downgrades enabled and IOCtrl_Update() command accepted

ERROR - IOCtrl_Update() command was not accepted

ERROR_NOT_SUPPORTED - Downgrades not enabled (IO Controller FW < 01v006)

IOCtrl_DisableDowngrade()

Disable IO Controller firmware downgrades

IOCtrl_Update()

Trigger IO Controller firmware update

If the firmware update was successful, the AppLog entry "MT_MODFWUPDATED" is generated when the IO controller restarts. The parameter specifies the previous and the current firmware version.

If no update has been performed, the AppLog entry "MT_MODFWUPDATED" is created where the parameter indicates why the update has not been performed.

returns : s32 - OK if command accepted, otherwise ERROR

Function works non-blocking. Status information will be passed to the function IOCtrl_UpdateCallback.

IOCtrl_UpdateCallback(res)

IO Controller firmware update Process completed (Callback for IOCtrl_Update() )

res - Resultcode

OK - Firmware update was successful

ERROR - General error during firmware update

C3_ERROR_FW_OLD_VERSION - see C3_ERROR_x

C3_ERROR_FW_SAME_VERSION - see C3_ERROR_x

IOCTRL_TIME_FLAG:

Control flags for Timesynch function IOCtrl_Time

IOCTRL_TIME_FLAG_FORCE_SYNCH - 0x0001 (Force Timesynch)

IOCTRL_ITV_TIME_CHECK -

interval [s] for verifying IO Controller time against M2M module time

Default value for IOCTRL_ITV_TIME_CHECK is 60s. It may be overruled by the user.

// Example #define IOCTRL_ITV_TIME_CHECK (120) // set to 120s

IOCtrl_Time(flags=0, stamp=0, stamp256=0)

IO Controller Timesynch function

flags - Control flags, see IOCTRL_TIME_FLAG

stamp - Timestamp [s], 0=use current system time

stamp256 - Timestamp [1/256s], 0=use current system time

returns : s32

OK - Command accepted

ERROR - If one of the following errors occurs

IO controller command is currently not allowed (init, reset, shutdown or update is in progress).

Command queue is full.

The timestamp must be provided in the Microtronics internal format. See rM2M_GetTime or rM2M_GetDateTime for more information.

The default functionality for this function (no parameters provided) is to compare the current system time from the M2M module against the current time available on the IOController. The deviation (number of seconds) is provided to callback function assigned to IOCTRL_TIME_CB. For triggering IO Controller timesynch the control flag IOCTRL_TIME_FLAG_FORCE_SYNCH must be set within flags parameter.

Function is called once if IO Controller Start/Restart was detected (with IOCTRL_TIME_FLAG_FORCE_SYNCH set) and periodically (see IOCTRL_ITV_TIME_CHECK) without having IOCTRL_TIME_FLAG_FORCE_SYNCH set. Full synch (IOCTRL_TIME_FLAG_FORCE_SYNCH) is automatically triggered if time deviation is <= -5sec or >= 5sec (arbitrary limit).

IOCTRL_TIME_CB(deviation)

Callback function for IOCtrl_Time

deviation : s32 - [s] Time deviation between M2M module and IOController

=0: synched properly
>0: M2M Timestamp is newer
<0: M2M Timestamp is older

C3_TriggerShutdown()

Shuts down the rapidM2M C3xx immediately in a controlled manner.

First, the applog entry "MT_SHUTDOWN" is generated, then all interfaces (CAN, RS232 and RS485) are closed and finally the IO controller is shut down.

No further commands are accepted and shutdown handling callbacks are suppressed during this time.

The device will restart automatically if the external supply voltage (VIN) recovers or is still active after the rapidM2M C3xx has been shut down.

It is recommended to stop any active uplink connections (using uplinkMode(UPLINK_TRIG) ) before calling this function.

Shutdown Handling

C3_SetShutdownTimeouts(iOutageTimeout=-1, iShutdownTimeout=-1)

Sets the timeouts used during the shutdown handling procedure.

If the timeouts are not set explicitly using this function, the default values (outage timeout = 5sec., shutdown timeout = 120sec.) are used.

Modifying a timeout that has already been started is not possible. The passed value is only used when the timeout is started the next time (i.e. at the next supply voltage failure).

iOutageTimeout : s32 - The time until IOCtrl_OutageTimeoutExpCallback() is called. [sec]

-1 - The outage timeout is not changed

>= 0 - The passed value is adopted (min = 1, max = 900)

The Timeout is started when the supply is switched to the rechargeable buffer battery (i.e. after IOCtrl_BackupSupplyOnCallback() was called)

iShutdownTimeout : s32 - The time until the rapidM2M C3xx is shutdown. [sec]

-1 - The shutdown timeout is not changed

>= 0 - The passed value is adopted (min = 1, max = 2700)

The Timeout is started after the outage timeout has expired. (i.e. after IOCtrl_OutageTimeoutExpCallback() was called)

returns : s32

OK - The Timeouts were successfully updated

C3_ERROR_BACKUP_OUTAGE_TIMEOUT - see C3_ERROR_x

C3_ERROR_BACKUP_SHTDWN_TIMEOUT - see C3_ERROR_x

Shutdown Handling

C3_GetBackupSupplyState()

Returns the current state of the backup supply.

returns : s32

0 - The rapidM2M C3xx device is supplied via the external supply voltage (VIN)

1 - The supply for the rapidM2M C3xx device is provided by the internal rechargeable buffer battery

Shutdown Handling

IOCtrl_BackupSupplyOnCallback()

The supply has been switched to the rechargeable buffer battery and the outage timeout was started. The applog entry "MT_BACKUPSUPPLY, MT_BACKUPSUPPLY_BATTERY_ACTIVE" is also generated.

The following components fail as soon as the rapidM2M C3xx is only supplied by the rechargeable buffer battery:

CAN (As a result also any communication with IO Extensions is not possible any more)

5V supply voltage at pin 9 of the RS232 interface

Relays

IOCtrl_OutageTimeoutExpCallback()

The outage timeout has expired and the rapidM2M C3xx is still supplied via the rechargeable buffer battery. The applog entry "MT_BACKUPSUPPLY, MT_BACKUPSUPPLY_OUTAGE_EXPIRED" is also generated.

It is recommended to generate 'Supply voltage failure' alarm/warning (using Alerts_CheckAlarm_f32() function of the "alerts-microtronics" libary), trigger a uplink synchronization (using uplinkFlush()) to inform the server about the supply voltage failure and shut down the rapidM2M C3xx afterwards (using C3_TriggerShutdown()).

IOCtrl_BackupSupplyOffCallback(iState)

The supply voltage is available again and the rechargeable buffer battery has been disabled. The applog entry "MT_BACKUPSUPPLY, MT_BACKUPSUPPLY_EXT_SUPPLY_ACT" is also generated.

If the supply voltage recovers the following components are available again:

CAN (As a result also any communication with IO Extensions is possible again)

5V supply voltage at pin 9 of the RS232 interface

Relays

iState : C3_STATE_BACKUP_x - Active state of the shutdown handling procedure when the supply voltage was available again and the rechargeable buffer battery has been disabled (see C3_STATE_x).

Depending on iState, reactions to switching to the rechargeable buffer battery may need to be undone (i.e. reset of active alarms/warnings).

C3_setLed(const rgb,const mode=LED_STATIC,count=0)

control the RGB Led

rgb : Trgb - 0xRRGGBB - 24bit color code, 0=turn off

CO_DEFAULT is not supported

Only base colors (CO_BLACK, CO_WHITE, CO_RED, CO_GREEN, CO_BLUE, CO_YELLOW, CO_CYAN and CO_MAGENTA ) are supported

Dimming (e.g. 50% red) is not possible.

mode : s32 - optional

LED_STATIC - (default)

LED_BLINK - 1s period, 500ms on, 500ms off

LED_FLICKER - 500ms period, single 30ms flash on

LED_FLASH - 120ms period, 90ms on, 30ms off

count : s32 - optional;

ignored for mode "LED_STATIC"

0 - forever (default)

>0 - Number of times the LED should blink, flicker or flash

C3_BUTTON_x:

Possible button events

C3_BUTTON_PRESSED - Button was pressed

C3_BUTTON_RELEASED - Button was released

C3_ButtonInit(event, callback)

Registers a callback for the specified button event

If a callback is already registerd, the callback is cleared before the new callback is registerd again.

It is not possible to register a callback for both button events at the same time. An alternative solution is presented below.

event : C3_BUTTON_x - The button event that triggers the callback

callback : C3_TonButton - The callback to execute

// --- // Watch for both button events // --- #callback onButtonEvent( buttonState) { // Watch for the next button event C3_ButtonInit( buttonState ? C3_BUTTON_PRESSED : C3_BUTTON_RELEASED, onButtonEvent); // Log the current button event #log( buttonState ? "released" : "pressed"); } main() { // Start button event handling // - needs decision to start with either button pressed or released event C3_ButtonInit( C3_BUTTON_PRESSED, onButtonEvent); }

C3_TonButton(released)

released : s32

0 - button has been pressed

1 - button has been released

C3_ButtonClose()

Close the button handling started with C3_ButtonInit()

Overview:

File handling (READ, WRITE, etc.) is currently not fully supported, it is currently only used internally for IO Controller Firmware Update.

IOCtrl_FileList()

List all available files

returns : s32 - result

OK - Command accepted

ERROR - If one of the following errors occurs

IO controller command is currently not allowed (init, reset, shutdown or update is in progress).

Command queue is full.

Command works non-blocking. Function mapped to IOCTRL_FILE_LIST_CB is called for every file available, IOCTRL_FILE_LIST_DONE_CB is called if command has finished.

IOCTRL_FILE_LIST_CB(sFileProps[TFT_Info])

sFileProps[TFT_Info] - File properties

Function is called if a valid File was found during File List command IOCtrl_FileList().

IOCTRL_FILE_LIST_DONE_CB(res)

res - OK if File List was successful, otherwise ERROR

Function is called if File List Command IOCtrl_FileList has finished.

IOCTRL_FILE_STORE_CB(id, sFileProps[TFT_Info])

File was stored on the IO Controller

id - File Transfer ID

sFileProps[TFT_Info] - File Transfer properties (name, size, crc, ...)

res - OK if download was successful, otherwise ERROR

This functions is called if a file download (currently only firmware files available) has finished.

TUIMode:

UI Channel Input Types

UI_CHT_SI_NONE - 0 (channel off)

UI_CHT_SI_DIGITAL - 1 (digital)

UI_CHT_SI_DCTR - 2 (counter)

UI_CHT_SI_DFREQ - 3 (frequency)

UI_CHT_SI_DPWM - 4 (pulse width modulation)

UI_CHT_SI_A020MA - 5 (0..20mA)

UI_CHT_SI_A002V - 6 (0..2V)

UI_CHT_SI_A010V - 7 (0..10V)

UI_CHT_SI_DIRECT - 8 (direct)

UI_CHANNEL:

UI Channel enumerator

UI_CHANNEL1 - 0

UI_CHANNEL2 - 1

UI_CHANNEL3 - 2

UI_CHANNEL4 - 3

UI_CHANNEL5 - 4

UI_CHANNEL6 - 5

UI_CHANNEL7 - 6

UI_CHANNEL8 - 7

UI_CHANNEL9 - 8

UI_CHANNEL10 - 9

UI_CHANNEL11 - 10

UI_CHANNEL12 - 11

UI_NUM_CHANNELS - 12

UI_NUM_CHANNELS is the overall max. number for all HW variants. The real number of available UI channels is available within TIOCtrl_Id struct (field .numUI).

UI_NUM_CHANNELS_BASE - 3

Number of UI channels of the rapidM2M C3xx base unit

UI_NUM_CHANNELS_IOEXT - 12

Number of UI channels of the rapidM2M C3e 12UI/2Rel extension module

IOCtrl_UI_Init(chnl, mode, filtertime=0, extSerial=-1)

Init an UI channel

chnl - UI channel to configure

Must not exceed the maximum number of UI channels available

UI_NUM_CHANNELS_BASE: Number of UI channels of the rapidM2M C3xx base unit

UI_NUM_CHANNELS_IOEXT: Number of UI channels of the rapidM2M C3e 12UI/2Rel extension module

mode - UI channel mode (TUIMode)

filtertime - Filtertime for channel in [ms].

Used for fast averaging of analog measurements (0..20mA, 0..2V, 0..10V, direct) or debouncing of digital value.

extSerial - serial number of the extension module, -1 if not used

returns : s32

OK - Command accepted

ERROR_NOT_SUPPORTED - Function not available, IO Controller firmware probably not up to date.

ERROR - If one of the following errors occurs

IOCtrl_UIInitCallback/IOExt_UIInitCallback not activated. Check your Library Config.

IO controller command is currently not allowed (init, reset, shutdown or update is in progress).

Command queue is full.

Command sequence is full.

IOCtrl_UI_Init works non-blocking. Callback function IOCtrl_UIInitCallback is triggered if command has finished and UI channel on the rapidM2M C3xx was selected (extSerial=-1). In case C3 extension module was selected (extSerial >= 0), function IOExt_UIInitCallback is triggered.

Command may be used within a command sequence. See Command Sequence Usage for more information.

IOCtrl_UIInitCallback(chnl, result)

UI channel init completed (Callback for IOCtrl_UI_Init(), rapidM2M C3xx)

chnl - UI Channel

result : s32 - Resultcode

OK: UI channel init was successful
ERROR_NOT_SUPPORTED: Not supported on this hardware / firmware
ERROR: any other error occured

IOExt_UIInitCallback(serial, chnl, result)

UI channel init completed (Callback for IOCtrl_UI_Init(), C3 IO Extension)

serial - serial number of the extension module

chnl - UI Channel

result : s32 - Resultcode

OK: UI channel init was successful
ERROR_NOT_SUPPORTED: Not supported on this hardware / firmware
ERROR: any other error occured

IOCtrl_UI_Close(chnl, extSerial=-1)

Close an UI channel

chnl - UI channel to close

extSerial - serial number of the extension module, -1 if not used

returns : s32

OK - Command accepted

ERROR_NOT_SUPPORTED - Function not available, IO Controller firmware probably not up to date.

ERROR - If one of the following errors occurs

IO controller command is currently not allowed (init, reset, shutdown or update is in progress).

Command queue is full.

Command sequence is full.

Function works non-blocking. No dedicated callback function is used if command has finished.

Command may be used within a command sequence. See Command Sequence Usage for more information.

IOCtrl_UI_GetValue(chnl=-1, extSerial=-1)

Get current UI channel value.

chnl - UI Channel. -1 if values from all channels should be read.

extSerial - serial number of the extension module, -1 if not used

returns : s32

OK - Command accepted

ERROR_NOT_SUPPORTED - Function not available, IO Controller firmware probably not up to date.

ERROR - If one of the following errors occurs

IOCtrl_UIValueCallback/IOExt_UIValueCallback not activated. Check your Library Config.

IO controller command is currently not allowed (init, reset, shutdown or update is in progress).

Command queue is full.

Command sequence is full.

Function works non-blocking. The channel value will be passed to the function IOCtrl_UIValueCallback if the rapidM2M C3xx was selected (extSerial=-1) or to the function IOExt_UIValueCallback if C3 extension module was selected (extSerial >= 0).

Command may be used within a command sequence. See Command Sequence Usage for more information.

IOCtrl_UIValueCallback(chnl, value)

Current UI channel value available (Callback for IOCtrl_UI_GetValue() )

chnl - UI Channel

value - Channel Value

Unit of channel value depending channel input configuration. [uA] for 0..20mA, [mV] for 0..2V/10V

IOExt_UIValueCallback(serial, chnl, value)

Current UI channel value is available (Callback for IOCtrl_UI_GetValue() )

serial - serial number of the extension module

chnl - UI Channel

value - Channel Value

Unit of channel value depending channel input configuration. [uA] for 0..20mA, [mV] for 0..2V/10V

IOCtrl_UI_GetLastDigital(chnl=-1, extSerial=-1)

Get stored values for Digital Input UI channel(s)

chnl - UI Channel. -1 if values from all channels configured as UI_CHT_SI_DIGITAL should be read.

extSerial - serial number of the extension module, -1 if not used

returns : s32

OK - Command accepted

ERROR_NOT_SUPPORTED - Function not available, IO Controller firmware probably not up to date.

ERROR - If one of the following errors occurs

IOCtrl_UIGetLastDigitalCallback/IOExt_UIGetLastDigitalCallback not activated. Check your Library Config.

IO controller command is currently not allowed (init, reset, shutdown or update is in progress).

Command queue is full.

Command sequence is full.

Function works non-blocking. Information will be passed to the function a IOCtrl_UIGetLastDigitalCallback if the rapidM2M C3xx was selected (extSerial=-1) or to the function IOExt_UIGetLastDigitalCallback if C3 extension module was selected (extSerial >= 0). The provided values will be stored if the digital input state changes and will be overwritten with the next input change. This function enables a precise measurement (+/-1ms) for digital ON and OFF time.

Command may be used within a command sequence. See Command Sequence Usage for more information.

IOCtrl_UIGetLastDigitalCallback(chnl, value, duration)

Last stored values for Digital Input UI channel is available (Callback for IOCtrl_UI_GetLastDigital() )

chnl - UI Channel

value - Last Channel Value (Digital: 0 or 1)

Right after calling IOCtrl_UI_Init the value will be initialized to -1. It depends on the configured filtertime when a valid digital value is available.

duration - Duration [ms] for last channel value

Right after calling IOCtrl_UI_Init the value will be 0.

The values provided do not hold the ACTUAL physical state, the hold the LAST one. Example: If input changes from 1 to 0 (falling edge), the LAST value (1) will be provided. Parameter duration will hold the milliseconds the LAST value was 1 (ON time). The values must be read until next digital state change is detected, otherwise information will be lost.

IOExt_UIGetLastDigitalCallback(serial, chnl, value, duration)

Last stored values for Digital Input UI channel is available (Callback for IOCtrl_UI_GetLastDigital() )

serial - serial number of the extension module

chnl - UI Channel

value - Last Channel Value (Digital: 0 or 1)

Right after calling IOCtrl_UI_Init the value will be initialized to -1. It depends on the configured filtertime when a valid digital value is available.

duration - Duration [ms] for last channel value

Right after calling IOCtrl_UI_Init the value will be 0.

The values provided do not hold the ACTUAL physical state, the hold the LAST one. Example: If input changes from 1 to 0 (falling edge), the LAST value (1) will be provided. Parameter duration will hold the milliseconds the LAST value was 1 (ON time). The values must be read until next digital state change is detected, otherwise information will be lost.

IOCtrl_UI_ResetCounter(chnl, extSerial=-1)

Reset counters and get value.

chnl - UI Channel to get value and reset counter

extSerial - serial number of the extension module, -1 if not used

returns : s32

OK - Command accepted

ERROR_NOT_SUPPORTED - Function not available, IO Controller firmware probably not up to date.

ERROR - If one of the following errors occurs

IOCtrl_UIResetCounterCallback/IOExt_UIResetCounterCallback not activated. Check your Library Config.

IO controller command is currently not allowed (init, reset, shutdown or update is in progress).

Command queue is full.

Command sequence is full.

Function works non-blocking. Function IOCtrl_UIResetCounterCallback is called if counter on the rapidM2M C3xx was reset (extSerial=-1). Function IOExt_UIResetCounterCallback is called if counter on C3 extension module was reset (extSerial >= 0).

Command may be used within a command sequence. See Command Sequence Usage for more information.

IOCtrl_UIResetCounterCallback(chnl, value)

The counter has been reset (Callback for IOCtrl_UI_ResetCounter() )

chnl - UI Channel

value - Channel Value (Last value before counter reset was performed)

IOExt_UIResetCounterCallback(serial, chnl, value)

The counter has been reset (Callback for IOCtrl_UI_ResetCounter() )

serial - serial number of the extension module

chnl - UI Channel

value - Channel Value (Last value before counter reset was performed)

UI_TRIG_TYPE:

Supported UI Trigger Types

UI_TRIG_TYPE_NONE - 0

UI_TRIG_TYPE_STD - 1 Standard Trigger

UI_TRIG_EVENT:

UI Trigger events

UI_TRIG_EVENT_NONE - 0

UI_TRIG_EVENT_START - 1 (Start condition)

UI_TRIG_EVENT_STOP - 2 (Stop condition)

UI_TRIG_EVENT_CHG - 3 (Value change)

UI_TRIG_EVENT_MIN - 4 (Min value)

UI_TRIG_EVENT_MAX - 5 (Max value)

UI_TRIG_STD_START_MODE:

Modes for starting UI Standard Trigger

UI_TRIG_STD_START_ALWAYS_ON - 0

UI_TRIG_EVENT_START is triggered immediately.

UI_TRIG_STD_START_GT_TH - 1

UI_TRIG_EVENT_START is triggered if current value exceeded configured fThresholdStart.

UI_TRIG_STD_STOP_MODE:

Modes for stopping UI Standard Trigger

UI_TRIG_STD_STOP_NEVER - 0

UI_TRIG_STD_STOP_TIMEOUT - 1

UI_TRIG_EVENT_STOP is triggered after timeout (elapsed ms since UI_TRIG_EVENT_START >= activeTimeout configuration)

UI_TRIG_STD_FLAG:

Configuration Flags (bitwise OR'able) for UI Standard Trigger

UI_TRIG_STD_FLAG_ENA_MIN - 0x0001 (Bit 0): Enable MIN trigger

MIN event is triggered if CHG trigger was detected (see UI_TRIG_STD_FLAG_ENA_CHG and UI_TRIG_STD_FLAG_ENA_CHGSUM) and signal trend changed from FALLING to RISING.

UI_TRIG_STD_FLAG_ENA_MAX - 0x0002 (Bit 1): Enable MAX trigger

MAX event is triggered if CHG trigger was detected (see UI_TRIG_STD_FLAG_ENA_CHG and UI_TRIG_STD_FLAG_ENA_CHGSUM), and signal trend changed from RISING to FALLING.

UI_TRIG_STD_FLAG_ENA_CHG - 0x0004 (Bit 2): Enable CHG trigger

Signal change was greater than configured deltaScale within configured deltaTime (transient detection). If deltaTime is zero (deactivated), only the signal change itself is estimated.

UI_TRIG_STD_FLAG_ENA_CHGSUM - 0x0008 (Bit 3): Enable CHG SUM trigger

Every processing cycle (according to parameter sampleRate) the signal difference (compared to last event, absolute value) is summed up. If the sum (integrated value) is greater than parameter deltaScaleSum, CHG event is triggered. This feature is meaningful to detect signal changes over time that are below deltaScale.

TUI_StdTrigInit:

UI Standard Trigger configuration

type - Trigger type, see UI_TRIG_TYPE

Field may left unconfigured, appropriate type UI_TRIG_TYPE_STD is filled automatically.

sampleRate : u16 - UI sample rate [Hz], 1 - 1000

warmupTime : u32 - Warmup time [ms]

Trigger processing is started if warmup time expired.

flags : u32 - Configuration flags, see UI_TRIG_STD_FLAG

modeStart : u8 - Trigger start mode, see UI_TRIG_STD_START_MODE

modeStop : u8 - Trigger stop mode, see UI_TRIG_STD_STOP_MODE

Float : fScale - Scaling factor for converting input signal to process value (e.g. mA -> bar)

Float : fOfs - Offset for converting input signal to process value

Float : fThresholdStart - Threshold value for Trigger start condition

Value is used if modeStart parameter is UI_TRIG_STD_ENA_GT_TH.

activeTimeout : u32 - Timeout [ms] for Trigger stop condition

Value is used if modeStop parameter is UI_TRIG_STD_DIS_TIMEOUT. UI_TRIG_EVENT_STOP is only triggered if START condition is not met after timeout.

Float : fDeltaScale - delta scale value for detecting value changes (0=disabled)

UI_TRIG_STD_FLAG_ENA_CHG (parameter iFlags) must be set to enable trigger event. If event is not enabled it is used to trigger MIN/MAX detection though.

deltaTime : u16 - delta time value (0=disabled)

fDeltaScale and deltaTime parameter may be used in combination for detecting transient signal changes - fDeltaScale must be exceeded within deltaTime.

Float : fDeltaScaleSum - delta scale value for detecting value changes (integrated, diff values summed up)

This threshold is intended to detect signal changes below fDeltaScale. UI_TRIG_STD_FLAG_ENA_CHGSUM (parameter iFlags) must be set to enable trigger event. If event is not enabled it is used to trigger MIN/MAX detection though.

Configuration values must be set carefully - e.g. too small selected threshold values may lead to a 'trigger event flood' that may cause exceptions within DLO (e.g. runtime exception).

IOCtrl_UI_StdTriggerInit(chnl, sInit[TUI_StdTrigInit])

Init Standard Trigger for UI channel

chnl - UI Channel

sInit[TUI_StdTrigInit] - Trigger configuration

returns : s32

OK - Command accepted

ERROR_NOT_SUPPORTED - Function not available, IO Controller firmware probably not up to date.

ERROR - If one of the following errors occurs

UI Channel number not valid.

Std. trigger already initialized for this channel.

IO controller command is currently not allowed (init, reset, shutdown or update is in progress).

Command queue is full.

Command sequence is full.

UI standard trigger is an algorithm intended to reduce the amount of measured values (e.g. only detect MIN/MAX values) though processing is fast (up to 1kHz). Several parameters (see TUI_StdTrigInit) are available to enable customization.

Basic UI channel must be initialized (IOCtrl_UI_Init) with proper analog mode (UI_CHT_SI_A020MA, UI_CHT_SI_A002V, UI_CHT_SI_A010V) before.

IOCtrl_UI_StdTriggerInit works non-blocking. Callback function IOCtrl_UITriggerInitCallback is triggered if command has finished.

Command may be used within a command sequence. See Command Sequence Usage for more information.

IOCtrl_UITriggerInitCallback(chnl, result)

Standard Trigger init for UI channel completed (Callback IOCtrl_UI_StdTriggerInit(), rapidM2M C3xx )

chnl - UI Channel

result : s32 - Resultcode

OK - UI trigger init was successful

ERROR_NOT_SUPPORTED - Not supported on this hardware / firmware

ERROR - any other error occured, e.g. basic UI channel not initialized or UI mode not valid, e.g. invalid configuration values (combination)

IOCtrl_UI_TriggerClose(chnl)

Close Trigger for UI channel

chnl - UI Channel

returns : s32

OK - Command accepted

ERROR_NOT_SUPPORTED - Function not available, IO Controller firmware probably not up to date.

ERROR - If one of the following errors occurs

IO controller command is currently not allowed (init, reset, shutdown or update is in progress).

Command queue is full.

Command sequence is full.

TUI_Trig:

UI Trigger data structure

stamp : u32 - Timestamp [s]

stamp256 : u8 - Timestamp [1/256s]

stamp1ms : u16 - Timestamp [ms]

msElapsed : u32 - Number of elapsed ms since last UI_TRIG_EVENT_START

event : u8 - Eventcode, see UI_TRIG_EVENT

Float : fValue - Trigger value

Entry stamp1ms is used to get more precise timestamp information. The default resolution is 1/256s (stamp256) = 3.91ms. If 1kHz samplerate is used the resolution is 1ms.

IOCTRL_UI_TRIGGER_READ_MAX -

20

This configuration is used to limit the number of trigger event entries for IOCtrl_UI_TriggerRead.

Only change this configuration if problems encountered - if the value is too high it may cause script runtime excpections.

IOCtrl_UI_TriggerRead(maxcnt=IOCTRL_UI_TRIGGER_READ_MAX)

Read available trigger events from IO controller

maxcnt - max. number of trigger events

returns : s32

OK - Command accepted

ERROR_NOT_SUPPORTED - Function not available, IO Controller firmware probably not up to date.

ERROR - If one of the following errors occurs

IO controller command is currently not allowed (init, reset, shutdown or update is in progress).

Command queue is full.

Command sequence is full.

Function works non-blocking. Function assigned to IOCTRL_UI_TRIGGER_READ_CB is called if triggerevent for UI channel on the rapidM2M C3xx was detected.

It is not necessary to call IOCtrl_UI_TriggerRead from user application, it is fully managed within DLO library if trigger event was indicated by the IO controller.

IOCTRL_UI_TRIGGER_READ_CB(chnl, sTrig[TUI_Trig])

Callback Function for IOCtrl_UI_TriggerRead

chnl - UI channel

sTrig[TUI_Trig] - Trigger information

Overview:

Prepare RS232 for use:

Configure IOCTRL_RS232_RXLEN and IOCTRL_RS232_TXLEN
Configure IOCtrl_RS232RxCallback (Rx Callback Function)
Init Interface
// Init RS232 Interface with baudrate 115200 and Mode 8N1 RS232_Init(RS232_ITF1, 115200, RS232_8_DATABIT | RS232_PARITY_NONE | RS232_1_STOPBIT);

IOCTRL_RS232_TXLEN -

Buffersize RS232 Tx FIFO

256 (Default)

This value can be overruled within custom inc file.

IOCTRL_RS232_RXLEN -

RS232 Read Length

256 (Default)

It specifies the max. number of bytes that will be passed to IOCtrl_RS232RxCallback. This value can be overruled within custom inc file.

RS232_ITF:

Available RS232 Interfaces

RS232_ITF1 = 0,

RS232_NUM_ITF = 1

RS232_xxx:

RS232 Configuration Bits (Bitmask)

RS232_1_STOPBIT - 0b0000000000000001, // 1 stop bit

RS232_2_STOPBIT - 0b0000000000000010, // 2 stop bits

RS232_PARITY_NONE - 0b0000000000000000, // no parity

RS232_PARITY_ODD - 0b0000000000000100, // odd parity

RS232_PARITY_EVEN - 0b0000000000001000, // even parity

RS232_7_DATABIT - 0b0000000000000000, // 7 data bits

RS232_8_DATABIT - 0b0000000000010000, // 8 data bits

RS232_FLOW_NONE - 0b0000000000000000, // no flow control

RS232_FLOW_RTSCTS - 0b0000000001000000, // RTS/CTS handshake

RS232_FULL_DUPLEX - 0b0000000000000000,

RS232_HALF_DUPLEX - 0b0000000100000000,

IOCtrl_RS232_Init(rs232, baudrate, mode)

Initialise RS232 interface.

rs232 - RS232 interface number, see RS232_ITF definitions

baudrate - baudrate

mode - see RS232_xxx bitmask definitions (7/8-bit Stopbit yes/no, Parity yes/no, etc.)

returns : s32

OK - Command accepted

ERROR - If one of the following errors occurs

IOCtrl_RS232RxCallback not activated. Check your Library Config.

RS232 interface number not valid.

IO controller command is currently not allowed (init, reset, shutdown or update is in progress).

Command queue is full.

Command works non-blocking. Function IOCtrl_RS232InitCallback is called if command has finished. Function IOCtrl_RS232RxCallback is called if receive data is available.

IOCtrl_RS232InitCallback(rs232, result)

RS232 interface initialization completed (Callback for IOCtrl_RS232_Init() )

rs232 - RS232 interface number, see RS232_ITF definitions

result : s32 - Resultcode

OK if Init was successful, otherwise ERROR

IOCtrl_RS232RxCallback(rs232, data{}, len)

Data was received via the RS232 interface (Callback for IOCtrl_RS232_Init() )

rs232 - RS232 interface number, see RS232_ITF definitions

data - Rx Buffer

len - Number of bytes within Rx Buffer, max. length according to IOCTRL_RS232_RXLEN

IOCtrl_RS232_Write(rs232, data{}, len)

Send data over RS232 interface.

rs232 - RS232 interface number, see RS232_ITF definitions

data - Data Buffer to send

len - Number of bytes to send

returns : s32

> = 0 - number of consumed bytes

ERROR - If one of the following errors occurs

RS232 interface not initialized.

RS232 interface number not valid.

Data will be buffered (FIFO) within script. FIFO size is configurable through IOCTRL_RS232_TXLEN. If not all bytes can be buffered (result < len), it is up to the user-application to handle this situation and prevent from data loss.

Command works non-blocking. Function IOCtrl_RS232WriteCallback is called if command has finished.

IOCtrl_RS232WriteCallback(rs232, result, written)

Process which sends data via the RS232 Interface was completed (Callback for IOCtrl_RS232_Write() )

rs232 - RS232 interface number, see RS232_ITF definitions

result : s32 - Resultcode

OK if successful, otherwise ERROR

written - Number of bytes written (only if result is OK)

IOCtrl_RS232_Close(rs232)

Close RS232 interface.

rs232 - RS232 interface number, see RS232_ITF definitions

returns : s32

OK - Command accepted

ERROR - If one of the following errors occurs

IO controller command is currently not allowed (init, reset, shutdown or update is in progress).

Command queue is full.

Function works in non-blocking mode. There is no dedicated callback function if command has finished.

Overview:

Prepare RS485 for use:

Configure IOCTRL_RS485_RXLEN and IOCTRL_RS485_TXLEN
Configure IOCtrl_RS485RxCallback (Rx Callback Function)
Init Interface
// Init RS485 Interface with baudrate 19200 and Mode 8N1 RS485_Init(RS485_ITF1, 19200, RS485_8_DATABIT | RS485_PARITY_NONE | RS485_1_STOPBIT);

IOCTRL_RS485_TXLEN -

Buffersize RS485 Tx FIFO

256 (Default)

This value can be overruled within custom inc file.

IOCTRL_RS485_RXLEN -

RS485 Read Length

256 (Default)

It specifies the max. number of bytes that will be passed to IOCtrl_RS485RxCallback. This value can be overruled within custom inc file.

RS485_ITF:

Available RS485 Interfaces

RS485_ITF1 = 0,

RS485_NUM_ITF = 1

RS485_xxx:

RS485 Configuration Bits (Bitmask)

RS485_1_STOPBIT - 0b0000000000000001, // 1 stop bit

RS485_2_STOPBIT - 0b0000000000000010, // 2 stop bits

RS485_PARITY_NONE - 0b0000000000000000, // no parity

RS485_PARITY_ODD - 0b0000000000000100, // odd parity

RS485_PARITY_EVEN - 0b0000000000001000, // even parity

RS485_7_DATABIT - 0b0000000000000000, // 7 data bits

RS485_8_DATABIT - 0b0000000000010000, // 8 data bits

RS485_HALF_DUPLEX - 0b0000000000000000,

RS485_FULL_DUPLEX - 0b0000000100000000,

RS485_120_OHM_NONE - 0b0000000000000000,

RS485_120_OHM_ACT - 0b0000001000000000,

RS485_BIAS_ON - 0b0000010000000000,

RS485_BIAS_OFF - 0b0000000000000000,

IOCtrl_RS485_Init(rs485, baudrate, mode)

Initialise RS485 interface.

rs485 - RS485 interface number, see RS485_ITF definitions

baudrate - baudrate

mode - see RS485_xxx bitmask definitions (7/8-bit Stopbit yes/no, Parity yes/no, etc.)

returns : s32

OK - Command accepted

ERROR - If one of the following errors occurs

IOCtrl_RS485RxCallback not activated. Check your Library Config.

RS485 interface number not valid.

IO controller command is currently not allowed (init, reset, shutdown or update is in progress).

Command queue is full.

Command works non-blocking. Function IOCtrl_RS485InitCallback is called if command has finished. Function IOCtrl_RS485RxCallback is called if receive data is available.

IOCtrl_RS485InitCallback(rs485, result)

RS485 interface initialization completed (Callback function for IOCtrl_RS485_Init() )

rs485 - RS485 interface number, see RS485_ITF definitions

result : s32 - Resultcode

OK if Init was successful, otherwise ERROR

IOCtrl_RS485RxCallback(rs485, data{}, len)

Data was received via the RS485 interface (Callback function for IOCtrl_RS485_Init() )

rs485 - RS485 interface number, see RS485_ITF definitions

data - Rx Buffer

len - Number of bytes within Rx Buffer, max. length according to IOCTRL_RS485_RXLEN

IOCtrl_RS485_Write(rs485, data{}, len)

Send data over RS485 interface.

rs485 - RS485 interface number, see RS485_ITF definitions

data - Data Buffer to send

len - Number of bytes to send

returns : s32

> = 0 - number of consumed bytes

ERROR - If one of the following errors occurs

RS485 interface not initialized.

RS485 interface number not valid.

Data will be buffered (FIFO) within script. FIFO size is configurable through IOCTRL_RS485_TXLEN. If not all bytes can be buffered (result < len), it is up to the user-application to handle this situation and prevent from data loss.

Command works non-blocking. Function IOCtrl_RS485WriteCallback is called if command has finished.

IOCtrl_RS485WriteCallback(rs485, result, written)

Process which sends data via the RS485 Interface was completed (Callback for IOCtrl_RS485_Write() )

rs485 - RS485 interface number, see RS485_ITF definitions

result : s32 - Resultcode

OK if Write was successful, otherwise ERROR

written - Number of bytes written (only if result is OK)

IOCtrl_RS485_Close(rs485)

Close RS485 interface.

rs485 - RS485 interface number, see RS485_ITF definitions

returns : s32

OK - Command accepted

ERROR - If one of the following errors occurs

IO controller command is currently not allowed (init, reset, shutdown or update is in progress).

Command queue is full.

Overview:

Prepare CAN for use:

Configure IOCTRL_CAN_TX_MSG (Number of messages within Tx FIFO)
Configure IOCtrl_CANRxCallback (Rx Message Callback)
Rx Filter Configuration
- Global Filter
  With the global filter the user decides, how to handle messages that did not pass any message filter. See CAN_FILTER_GLOBAL definitions.
- Message Filter
Init Interface
new sCAN_Init[TCAN_Init]; /* Prepare CAN Interface configuration */ sCAN_Init.bitrateNominal = CAN_BITRATE_500KBIT; sCAN_Init.bitrateData = CAN_BITRATE_2MBIT; sCAN_Init.mode = CAN_MODE_NORMAL; sCAN_Init.flags = CAN_CFG_AUTO_RETRANSMISSION; sCAN_Init.filterGlobal = 0; // discard non-matching messages sCAN_Init.nStdFilter = N_CAN_STD_FILTER; sCAN_Init.nExtFilter = N_CAN_EXT_FILTER; IOCtrl_CAN_Init(0, sCAN_Init, asCAN_StdFilter, asCAN_ExtFilter);

IOCTRL_CAN_TX_MSG -

Number of entries within CAN Tx Message Buffer

32 (Default)

This value can be overruled within custom inc file.

CAN_ITF:

Available CAN interfaces

CAN_ITF1 - 0

CAN_NUM_ITF - 1

CAN_BYTES:

Supported Data Length Values

CAN_BYTES_0 - 0

CAN_BYTES_1 - 1

CAN_BYTES_2 - 2

CAN_BYTES_3 - 3

CAN_BYTES_4 - 4

CAN_BYTES_5 - 5

CAN_BYTES_6 - 6

CAN_BYTES_7 - 7

CAN_BYTES_8 - 8

CAN_BYTES_12 - 12 (only CAN FD)

CAN_BYTES_16 - 16 (only CAN FD)

CAN_BYTES_20 - 20 (only CAN FD)

CAN_BYTES_24 - 24 (only CAN FD)

CAN_BYTES_32 - 32 (only CAN FD)

CAN_BYTES_48 - 48 (only CAN FD)

CAN_BYTES_64 - 64 (only CAN FD)

CAN_STANDARD_ID -

0x00000000 (Bitmask) - 11-bit Id

CAN_EXTENDED_ID -

0x40000000 (Bitmask) - 29-bit Id

CAN_DATA_FRAME -

0x00000000 (Bitmask)

CAN_REMOTE_FRAME -

0x20000000 (Bitmask)

CAN_CFG:

CAN Configuration Flags (Bitmask)

CAN_CFG_AUTO_RETRANSMISSION - 0x00000001

CAN_CFG_TRANSMIT_PAUSE - 0x00000002

CAN_ESI_ACTIVE -

0x00000000 (Bitmask, Transmitting node is error active)

CAN_ESI_PASSIVE -

0x80000000 (Bitmask, Transmitting node is error passive)

CAN_BRS_OFF -

0x00000000 (CAN FD frames transmitted/received without bit rate switching)

CAN_BRS_ON -

0x00100000 (CAN FD frames transmitted/received with bit rate switching)

CAN_CLASSIC_CAN -

0x00000000 (Bitmask, Frame transmitted/received in Classic CAN format)

CAN_FD_CAN -

0x00200000 (Bitmask, Frame transmitted/received in CAN FD format)

CAN_TX_EVENTS:

CAN Tx Event Fifo Control

CAN_NO_TX_EVENTS - 0x00000000 (Do not store Tx events)

CAN_STORE_TX_EVENTS - 0x00800000 (Store Tx events)

TCAN_TxHeader:

CAN Tx Header structure

Identifier - CAN_STANDARD_ID - 0-0x7FF (11-bit), CAN_EXTENDED_ID - 0-0x1FFFFFFF (29-bit)

IdType - CAN_STANDARD_ID or CAN_EXTENDED_ID

TxFrameType - CAN_DATA_FRAME or CAN_REMOTE_FRAME

DataLength - see CAN_BYTES

ErrorStateIndicator - CAN_ESI_ACTIVE or CAN_ESI_PASSIVE

BitRateSwitch - CAN_BRS_ON or CAN_BRS_OFF

FDFormat - CAN_CLASSIC_CAN or CAN_FD_CAN

TxEventFifoControl - see CAN_TX_EVENTS

MessageMarker - 0-0xFF, Specifies the message marker to be copied into Tx Event FIFO element for identification of Tx message status

TCAN_RxHeader:

CAN Rx Header structure

Identifier - CAN_STANDARD_ID - 0-0x7FF (11-bit), CAN_EXTENDED_ID - 0-0x1FFFFFFF (29-bit)

IdType - CAN_STANDARD_ID or CAN_EXTENDED_ID

RxFrameType - CAN_DATA_FRAME or CAN_REMOTE_FRAME

DataLength - see CAN_BYTES

ErrorStateIndicator - CAN_ESI_ACTIVE or CAN_ESI_PASSIVE

BitRateSwitch - CAN_BRS_ON or CAN_BRS_OFF

FDFormat - CAN_CLASSIC_CAN or CAN_FD_CAN

RxTimestamp - 0-0xFFFF, Specifies the timestamp counter value captured on start of frame reception.

FilterIndex - Specifies the index of matching Rx acceptance filter element, 0-127 if IdType is CAN_STANDARD_ID, 0-63 if IdType is CAN_EXTENDED_ID

IsFilterMatchingFrame - 1=The accepted frame did match any Rx filter

CAN_EVT_RX:

CAN Rx Events (unsolicited UART response)

CAN_EVT_RX_MSGLOST - -1 (Message Lost)

CAN_EVT_RX_MSGNEW - 0 (New message available)

CAN_EVT_RX_FIFO_WATERMARK - 1 (Rx FIFO Watermark, IFO 3/4 filled)

CAN_EVT_RX_FIFO_FULL - 2 (Rx FIFO Full)

CAN_STAT:

CAN Protocol Status Information

CAN_STAT_EP - 0x00000001 (Error Passive)

0=The FDCAN is in the Error_Active state. It normally takes part in bus communication and sends an active error flag when an error has been detected. 1=The FDCAN is in Error_Passive state.

CAN_STAT_EW - 0x00000002 (Warning Status)

0=Both Error Counters are below the Error_Warning limit of 96 1=At least one of the error counter has reaches the Error_Warning limit of 96

CAN_STAT_BO - 0x00000004 (Bus_Off Status)

0=The FDCAN is not Bus_Off 1=The FDCAN is in Bus_Off state

CAN_STAT_PXE - 0x00000008 (Protocol Exception Event)

0=No protocol exception event occured since last read access 1=Protocol exception event occured

CAN_PROTOCOL_ERROR:

CAN Protocol Error

CAN_PROTOCOL_ERROR_NONE - 0 (No error occurred)

CAN_PROTOCOL_ERROR_NO_CHANGE - 7 (No change since last read)

CAN_PROTOCOL_ERROR_STUFF - 1 (Stuff error)

More than 5 equal bits in a sequence have occurred in a part of a received message where this is not allowed.

CAN_PROTOCOL_ERROR_FORM - 2 (Form error)

A fixed format part of a received frame has the wrong format.

CAN_PROTOCOL_ERROR_ACK - 3 (Acknowledge error)

The message transmitted was not acknowledged by another node.

CAN_PROTOCOL_ERROR_BIT1 - 4 (Bit 1 (recessive) error)

During the transmission of a message (with the exception of the arbitration field), the device wanted to send a recessive level (bit of logical value ‘1’), but the monitored bus value was dominant.

CAN_PROTOCOL_ERROR_BIT0 - 5 (Bit 0 (dominant) error)

During the transmission of a message (or acknowledge bit, or active error flag, or overload flag), the device wanted to send a dominant level (data or identifier bit logical value ‘0’), but the monitored bus value was recessive. During Bus_Off recovery this status is set each time a sequence of 11 recessive bits has been monitored. This enables the CPU to monitor the proceeding of the Bus_Off recovery sequence (indicating the bus is not stuck at dominant or continuously disturbed).

CAN_PROTOCOL_ERROR_CRC - 6 (CRC check sum error)

The CRC check sum of a received message was incorrect. The CRC of an incoming message does not match with the CRC calculated from the received data.

TCAN_Stat:

CAN Status information structure

cntTxErr - Transmit Error Counter Value (0-255)

cntRxErr - Receive Error Counter Value (0-127)

rxPassive - Receive Error Passive status

0=Receive Error Counter is below the error passive level of 128 1=Receive Error Counter has reached the error passive level of 128

logging - Transmit/Receive Error Logging Counter Value (0-255)

This counter is incremented each time when a FDCAN protocol error causes the TxErrorCnt or the RxErrorCnt to be incremented. The counter stops at 255.

stat - Protocol Status (Bitmask), see CAN_STAT definitions

cntRxFull - Number of Rx 'FIFO Full' events, see CAN_EVT_RX

cntRxMsgLost - Number of Rx 'Message Lost' events, see CAN_EVT_RX

cntRxWatermark - Number of Rx 'Watermark' events (Rx FIFO 75% filled), see CAN_EVT_RX

protocolError - Protocol Error, see CAN_PROTOCOL_ERROR

protocolErrorData - Protocol Error during Data Phase, see CAN_PROTOCOL_ERROR

When a frame in CAN FD format has reached the data phase with BRS flag set, the next CAN event (error or valid frame) will be shown in protocolErrorData instead of protocolError. An error in a fixed stuff bit of a CAN FD CRC sequence will be shown as a CAN_PROTOCOL_ERROR_FORM, not CAN_PROTOCOL_ERROR_STUFF.

CAN_FILTER_GLOBAL:

CAN Global Filter Configuration (Bitmask)

CAN_FILTER_GLOBAL_STD - 0x0001 (Pass non-matching 11-bit IDs)

CAN_FILTER_GLOBAL_EXT - 0x0002 (Pass non-matching 29-bit IDs)

CAN_FILTER_GLOBAL_REMOTE_STD - 0x0004 (Pass non-matching remote 11-bit IDs)

CAN_FILTER_GLOBAL_REMOTE_EXT - 0x0008 (Pass non-matching remote 29-bit IDs)

CAN_FILTER_TYPE:

Type of CAN Filter

CAN_FILTER_TYPE_RANGE - 0 (Range filter from FilterID1 to FilterID2)

CAN_FILTER_TYPE_DUAL - 1 (Dual ID filter for FilterID1 or FilterID2)

CAN_FILTER_TYPE_MASK - 2 (Classic filter: FilterID1 = filter, FilterID2 = mask)

CAN_FILTER_TYPE_RANGE_NO_EIDM - 3 (Range filter from FilterID1 to FilterID2, EIDM mask not applied)

Only applicable if IdType is CAN_EXTENDED_ID

CAN_FILTER_CFG:

CAN Filter Configuration

CAN_FILTER_CFG_DISABLE - 0 (Disable filter element)

CAN_FILTER_CFG_RXFIFO0 - 1 (Store in Rx FIFO 0 if filter matches)

// = AN_FILTER_CFG_RXFIFO1 - 2 (Store in Rx FIFO 1 if filter matches)

CAN_FILTER_CFG_REJECT - 3 (Reject ID if filter matches)

// = AN_FILTER_CFG_HP - 4 (Set high priority if filter matches)

// = AN_FILTER_CFG_RXFIFO0_HP - 5 (Set high priority and store in FIFO 0 if filter matches)

// = AN_FILTER_CFG_RXFIFO1_HP - 6 (Set high priority and store in FIFO 1 if filter matches)

// = AN_FILTER_CFG_RXBUFFER - 7 (Store into Rx Buffer, configuration of FilterType ignored)

TCAN_Filter:

CAN Filter configuration structure

Type - see CAN_FILTER_TYPE

Config - Specifies the filter configuration, see CAN_FILTER_CFG

ID1 - Specifies the filter identification 1 (meaning depending on CAN_FILTER_TYPE)

CAN_STANDARD_ID - Value between 0 and 0x7FF CAN_EXTENDED_ID: Value between 0 and 0x1FFFFFFF

ID2 - Specifies the filter identification 2 (meaning depending on CAN_FILTER_TYPE)

CAN_STANDARD_ID - Value between 0 and 0x7FF CAN_EXTENDED_ID: Value between 0 and 0x1FFFFFFF

TCAN_Init:

CAN configuration structure

bitrateNominal - Nominal Bitrate (classic CAN), see TCANBitrate definitions

bitrateData - Data Bitrate, see TCANBitrate definitions

=0: CAN FD is not used (only classic CAN)
=bitrateNominal: CAN FD without BRS enabled
>bitrateNominal: CAN FD with BRS enabled

Especially if CAN FD with BRS is used, a proper termination (120 Ohm) on both bus ends is required.

mode - CAN Operating Mode, see TCANOperatingMode definitions

flags - CAN Configuration Flags, see CAN_CFG definitions

filterGlobal - CAN Global Filter Configuration, see CAN_FILTER_GLOBAL definitions

nStdFilter - Number of entries within Std Filter Configuration List

nExtFilter - Number of entries within Ext Filter Configuration List

CANBittiming:

Default CAN Bittiming

Bit sampling is driven by a 80MHz clock with a configurable prescaler (PRS). 1 Time Quanta tq = 1 / (80MHz / PRS). Following segments will be passed for every bit:

Sync Segment - tsync (fixed to 1 tq)
Time Segment before Sample-Point - tseg1 (configurable)
Named Propagation-Delay and Phase Buffer Segment1 in ISO 11898-1:2015 Standard.
Time Segment afer Sample-Point - tseg2 (configurable)
Named Phase Buffer Segment2 in ISO 11898-1:2015 Standard.

sjw (re-synchronization jump width) is used to shorten tseg2 in case of re-synchronization (CAN Controller internals). Following configuration is used according to selected bitrate:

CAN_BITTIMING_10KBIT - 10kBit

PRS=400, 20 tq, tseg1=16, tseg2=3, sjw=3, SamplePoint=85%

CAN_BITTIMING_20KBIT - 20kBit

PRS=200, 20 tq, tseg1=16, tseg2=3, sjw=3, SamplePoint=85%

CAN_BITTIMING_50KBIT - 50kBit

PRS=80, 20 tq, tseg1=16, tseg2=3, sjw=3, SamplePoint=85%

CAN_BITTIMING_125KBIT - 125kBit

PRS=32, 20 tq, tseg1=16, tseg2=3, sjw=3, SamplePoint=85%

CAN_BITTIMING_250KBIT - 250kBit

PRS=16, 20 tq, tseg1=16, tseg2=3, sjw=3, SamplePoint=85%

CAN_BITTIMING_500KBIT - 500kBit

PRS=8, 20 tq, tseg1=16, tseg2=3, sjw=3, SamplePoint=85%

CAN_BITTIMING_800KBIT - 800kBit

PRS=5, 20 tq, tseg1=16, tseg2=3, sjw=3, SamplePoint=85%

CAN_BITTIMING_1MBIT - 1MBit

PRS=4, 20 tq, tseg1=16, tseg2=3, sjw=3, SamplePoint=85%

CAN_BITTIMING_2MBIT - 2MBit

PRS=2, 20 tq, tseg1=16, tseg2=3, sjw=3, SamplePoint=85%

CAN_BITTIMING_5MBIT - 5MBit

PRS=1, 16 tq, tseg1=13, tseg2=2, sjw=2, SamplePoint=87,5%

CAN_BITTIMING_8MBIT - 8MBit

PRS=1, 10 tq, tseg1=7, tseg2=2, sjw=2, SamplePoint=80%

TCANBitrate:

Supported CAN(CAN FD) Bitrates

CAN_BITRATE_10KBIT - 10000

CAN_BITRATE_20KBIT - 20000

CAN_BITRATE_50KBIT - 50000

CAN_BITRATE_125KBIT - 125000

CAN_BITRATE_250KBIT - 250000

CAN_BITRATE_500KBIT - 500000

CAN_BITRATE_800KBIT - 800000

CAN_BITRATE_1MBIT - 1000000

CAN_BITRATE_2MBIT - 2000000 (only CAN FD)

CAN_BITRATE_5MBIT - 5000000 (only CAN FD)

CAN_BITRATE_8MBIT - 8000000 (only CAN FD)

TCANOperatingMode:

Supported CAN Operating Modes

CAN_MODE_NORMAL - 0 (Normal mode)

CAN_MODE_RESTRICTED_OPERATION - 1 (Restricted Operation mode)

In Restricted Operation Mode the node is able to receive data and remote frames and to give acknowledge to valid frames, but it does not send data frames, remote frames, active error frames, or overload frames. In case of an error condition or overload condition, it does not send dominant bits, instead it waits for the occurrence of bus idle condition to resynchronize itself to the CAN communication.

CAN_MODE_BUS_MONITORING - 2 (Bus Monitoring mode)

In Bus Monitoring Mode (see ISO 11898-1:2015, 10.14 Bus monitoring), the device is able to receive valid data frames and valid remote frames, but cannot start a transmission. In this mode, it sends only recessive bits on the CAN bus.

CAN_MODE_INTERNAL_LOOPBACK - 3 (Internal LoopBack mode)

This mode can be used for a 'Hot Selftest', meaning the device can be tested without affecting a running CAN system connected to the pins. In this mode pin can_rx is disconnected from the CAN controller and pin can_tx is held recessive.

CAN_MODE_EXTERNAL_LOOPBACK - 4 (External LoopBack mode)

In LoopBack Mode, the CAN controller treats its own transmitted messages as received messages and stores them (if they pass acceptance filtering) into an Rx Buffer or an Rx FIFO.

CAN_USAGE_MODE:

Usage Modes for CAN interface

CAN_USAGE_MODE_RAW - 0 (RAW mode, full access to CAN interface from appliaction)

CAN_USAGE_MODE_IO_EXTENSION - 1 (Use managed CAN interface for IO Extensions)

IOCtrl_CAN_SetMode(can, mode)

Set usage mode for CAN interface

can - CAN Interface number, see CAN_ITF defintions

mode - CAN usage mode, see CAN_USAGE_MODE

returns : s32 - Result

OK: Command accepted
ERROR_NOT_SUPPORTED: Mode not supported, IO Controller firmware probably not up to date
ERROR: any other error occured

If IOExt_Init function is used, this function is called implicit. If mode CAN_USAGE_MODE_IO_EXTENSION is used, all dedicated CAN functions (e.g. IOCtrl_CAN_Init, IOCtrl_CAN_Write) are not allowed.

IOCtrl_CAN_Init(can, sInit[TCAN_Init], asStdFilter[][TCAN_Filter], asExtFilter[][TCAN_Filter])

Initialise CAN Interface

can - CAN Interface number, see CAN_ITF definitions

sInit : TCAN_Init - Global Configuration

asStdFilter : TCAN_Filter - Filter Configuration for CAN 11-bit IDs

asExtFilter : TCAN_Filter - Filter Configuration for CAN 29-bit IDs

returns : s32

OK - Command accepted

ERROR - If one of the following errors occurs

IOCtrl_CANRxCallback not activated. Check your Library Config.

CAN interface probably used for IO extension.

CAN interface number not valid.

IO controller command is currently not allowed (init, reset, shutdown or update is in progress).

Command queue is full.

Command works non-blocking. Function IOCtrl_CANInitCallback is called if command has finished. Function IOCtrl_CANRxCallback is called if a message was received.

IOCtrl_CANInitCallback(can, result)

CAN interface initialization completed (Callback for IOCtrl_CAN_Init() )

can - CAN interface number, see CAN_ITF definitions

result : s32 - Resultcode

OK if Init was successful, otherwise ERROR

IOCtrl_CANRxCallback(can, sRxHeader[TCAN_RxHeader], data{})

Message was received via the CAN interface (Callback for IOCtrl_CAN_Init() )

can - CAN Interface number, see CAN_ITF defintions

sRxHeader[TCAN_RxHeader] - Message Header

data - Message Data (Data Length according to sRxHeader.DataLength)

IOCtrl_CAN_Write(can, sTxHeader[TCAN_TxHeader], data{})

Write CAN Message

can - CAN Interface number, see CAN_ITF defintions

sTxHeader[TCAN_TxHeader] - Message Header

data - Message Data (Data Length according to sTxHeader.DataLength)

returns : s32

OK - Command accepted

ERROR - If one of the following errors occurs

CAN interface probably used for IO extension.

CAN interface not initialized.

CAN interface number not valid.

message buffer (FIFO) full.

IO controller command is currently not allowed (init, reset, shutdown or update is in progress).

Command queue is full.

Data will be buffered (FIFO) within script. FIFO size is configurable through IOCTRL_CAN_TX_MSG.

Command works non-blocking. Function IOCtrl_CANWriteCallback is called if command has finished.

IOCtrl_CANWriteCallback(can, result, msg, bytes)

Process which sends a message via the CAN Interface was completed (Callback for IOCtrl_CAN_Write() )

can - CAN interface number, see CAN_ITF definitions

returns : s32 - result

OK if Write was successful, otherwise ERROR

msg - Number of messages written (only valid if result is OK)

bytes - Number of bytes written (header and payload, only valid if result is OK)

IOCtrl_CAN_Close(can)

Close CAN Interface

can - CAN Interface number, see CAN_ITF defintions

returns : s32

OK - Command accepted

ERROR - If one of the following errors occurs

CAN interface probably used for IO extension.

CAN interface number not valid.

IO controller command is currently not allowed (init, reset, shutdown or update is in progress).

Command queue is full.

IOCtrl_CAN_GetStat(can)

Get current CAN Interface Status

can - CAN Interface number, see CAN_ITF defintions

returns : s32

OK - Command accepted

ERROR - If one of the following errors occurs

IOCtrl_CANGetStatCallback not activated. Check your Library Config.

CAN interface probably used for IO extension.

CAN interface not initialized.

CAN interface number not valid.

IO controller command is currently not allowed (init, reset, shutdown or update is in progress).

Command queue is full.

Function works non-blocking. Function IOCtrl_CANGetStatCallback will be called if CAN status information is available.

IOCtrl_CANGetStatCallback(can, sStat[TCAN_Stat])

CAN status information is available (Callback for IOCtrl_CAN_GetStat() )

can - CAN Interface number, see CAN_ITF defintions

sStat[TCAN_Stat] - CAN Status Information

DIGOUT_CHANNEL:

Digout Channel enumerator

DIGOUT_CHANNEL1 - 0

DIGOUT_CHANNEL2 - 1

DIGOUT_CHANNEL3 - 2

DIGOUT_CHANNEL4 - 3

DIGOUT_CHANNEL5 - 4

DIGOUT_CHANNEL6 - 5

DIGOUT_NUM_CHANNELS - 6

DIGOUT_NUM_CHANNELS is the overall max. number for all HW variants. The real number of available DIGOUT channels is available within TIOCtrl_Id struct (field .numDIGOUT).

DIGOUT_MODE:

Available Digout Modes

DIGOUT_OFF - 0

DIGOUT_DIG - 1

DIGOUT_FREQ - 2

DIGOUT_PWM - 3

DIGOUT_IMPULSE_PER_MINUTE - 4

DIGOUT_IMPULSE_ONCE - 5

DIGOUT_NUM_MODES - 6

The 'impulse output modes' (DIGOUT_FREQ, DIGOUT_PWM, DIGOUT_IMPULSE_PER_MINUTE and DIGOUT_IMPULSE_ONCE) are not available on every HW variant.

IOCtrl_DigOut_Init(digout, mode, cfg1=-1, cfg2=-1, extSerial=-1)

Init a digital output channel

digout - Digital Output

see DIGOUT_CHANNEL

mode - Output mode of the digital output

see DIGOUT_MODE

cfg1 - Config Parameter 1 for the output mode

Digout mode dependant

DIGOUT_DIG - not used
DIGOUT_FREQ - Output Duty Cycle
Value between 1% and 100%, default = 50%
DIGOUT_PWM - Frequency of the PWM
Value between 0 Hz and 1000 Hz, default = 100 Hz
DIGOUT_IMPULSE_PER_MINUTE - Length of the impulse
Value depends on UI_Samplerate, default = 100 ms
DIGOUT_IMPULSE_ONCE - Length of the impulse
Value between 1 ms and 500 ms, default = 100 ms

cfg2 - Config Parameter 2 for the output mode

Digout mode dependant

DIGOUT_DIG - not used
DIGOUT_FREQ - not used
DIGOUT_PWM - not used
DIGOUT_IMPULSE_PER_MINUTE - not used
DIGOUT_IMPULSE_ONCE - Pause length of the impulse
Value between 1 ms and 500 ms, default = 100 ms

extSerial - serial number of the extension module, -1 if not used

returns : s32

OK - Command accepted

ERROR_NOT_SUPPORTED - If one of the following errors occurs

Not supported on this HW version (only rapidM2M C3xx Rev. >=1.3)

Function not available, IO Controller firmware probably not up to date

ERROR - If one of the following errors occurs

IO controller command is currently not allowed (init, reset, shutdown or update is in progress).

Command queue is full.

Command sequence is full.

IOCtrl_DigOut_Init works non-blocking. Callback function IOCtrl_DigOutInitCallback is triggered if command has finished and DIGOUT channel on the rapidM2M C3xx was selected (extSerial=-1). In case C3 extension module was selected (extSerial >= 0), function IOExt_DigOutInitCallback is triggered.

Command may be used within a command sequence. See Command Sequence Usage for more information.

IOCtrl_DigOutInitCallback(digout, result)

Digital output channel init completed (Callback for IOCtrl_DigOut_Init(), rapidM2M C3xx)

digout - Digital Output, see DIGOUT_CHANNEL

result : s32 - Resultcode

OK: DIGOUT channel init was successful
ERROR_NOT_SUPPORTED: Not supported on this hardware / firmware
ERROR: any other error occured

IOExt_DigOutInitCallback(serial, digout, result)

Digital output channel init completed (Callback for IOCtrl_DigOut_Init(), C3 IO Extension)

serial - Serial number of the IO Extension module

digout - Digital Output, see DIGOUT_CHANNEL

result : s32 - Resultcode

OK: DIGOUT channel init was successful
ERROR_NOT_SUPPORTED: Not supported on this hardware / firmware
ERROR: any other error occured

IOCtrl_DigOut_Close(digout, extSerial=-1)

Close the digital output interface

digout - Digital Output, see DIGOUT_CHANNEL

returns : s32

OK - Command accepted

ERROR_NOT_SUPPORTED - Function not available, IO Controller firmware probably not up to date.

ERROR - If one of the following errors occurs

IO controller command is currently not allowed (init, reset, shutdown or update is in progress).

Command queue is full.

Command sequence is full.

Command may be used within a command sequence. See Command Sequence Usage for more information.

IOCtrl_DigOut_SetValue(digout, value, extSerial=-1)

Set/Clear Digital Output

digout - Digital Output

see DIGOUT_CHANNEL

value - Digout mode dependant

DIGOUT_DIG - Relay
0=OFF, 1=ON
DIGOUT_FREQ - Frequency
Value between 1 Hz and 1000 Hz
DIGOUT_PWM - Duty Cycle
Value between 0 % and 100 %
DIGOUT_IMPULSE_PER_MINUTE - Number of impulses per minute
ERROR if value is 0. Make sure that the length of the impulse isn't too long for the number of impulses per minute - output is zeroed otherwise. The max. duty cycle is 50%. Example: Value = 60, i.e. one impulse per second -> Impulse length is max. 500ms (50% Duty Cycle).
DIGOUT_IMPULSE_ONCE - Number of impulses
Number of consecutive impulses to generate

extSerial - serial number of the extension module, -1 if not used

returns : s32

OK - Command accepted

ERROR_NOT_SUPPORTED - Function not available, IO Controller firmware probably not up to date.

ERROR - If one of the following errors occurs

Digital Output channel not initialized.

IO controller command is currently not allowed (init, reset, shutdown or update is in progress).

Command queue is full.

Command sequence is full.

DigOut channel must be initialized through IOCtrl_DigOut_Init function before usage.

IOCtrl_DigOut_SetValue works non-blocking. Callback function IOCtrl_DigOutSetValueCallback is triggered if command has finished and DigOut channel on the rapidM2M C3xx was selected (extSerial=-1). In case C3 extension module was selected (extSerial >= 0), function IOExt_DigOutSetValueCallback is triggered.

Command may be used within a command sequence. See Command Sequence Usage for more information.

IOCtrl_DigOutSetValueCallback(digout, result, value)

Process which sets/clears digital output was completed (Callback for IOCtrl_DigOut_SetValue(), rapidM2M C3xx)

digout - Digital Output, see DIGOUT_CHANNEL

result : s32 - Resultcode

OK: DIGOUT channel value was set
ERROR_NOT_SUPPORTED: Not supported on this hardware / firmware
ERROR: any other error occured

value - DIGOUT channel value

IOExt_DigOutSetValueCallback(serial, digout, result, value)

Process which sets/clears digital output was completed (Callback for IOCtrl_DigOut_SetValue(), C3 IO Extension)

serial - Serial number of the IO Extension module

digout - Digital Output, see DIGOUT_CHANNEL

result : s32 - Resultcode

OK: DIGOUT channel was set
ERROR_NOT_SUPPORTED: Not supported on this hardware / firmware
ERROR: any other error occured

value - DIGOUT channel value

AO_CHANNEL:

AO Channel enumerator

AO_CHANNEL1 - 0

AO_CHANNEL2 - 1

AO_CHANNEL3 - 2

AO_NUM_CHANNELS - 3

AO_NUM_CHANNELS is the overall max. number for all HW variants. The real number of available channels is available within TIOCtrl_Id struct (field .numAO_mA for mA Outputs).

AO_MODE:

Analog Output Modes

AO_MODE_OFF - 0 (channel off)

AO_MODE_0_20mA - 1 (0-20mA)

AO_MODE_4_20mA - 2 (4-20mA)

AO_MODE_0_24mA - 3 (0-24mA)

AO_STAT:

Analog Output Status (Bitmask)

AO_STAT_OL - 0x01 (Bit0: Open-loop in external circuit detected, Optocoupler readback)

AO_STAT_IFAULT - 0x02 (Bit1: DAC Fault: Open-loop or insufficient power supply)

IOCtrl_AO_Init(chnl, mode, extSerial=-1)

Init analog output channel

chnl : u8 - Output channel

The number of available output channels depends on the selected module and is available within ID information (see TIOCtrl_Id).

mode : u8 - Output mode, see AO_MODE definitions

extSerial : s32 - serial number of the extension module, -1 if not used

Currently there is no rapidM2M C3xx hardware with analog outputs available.

returns : s32

OK - Command accepted

ERROR_NOT_SUPPORTED - Function not available, IO Controller firmware probably not up to date

ERROR - If one of the following errors occurs

IO controller command is currently not allowed (init, reset, shutdown or update is in progress).

Command queue is full.

Command sequence is full.

IOCtrl_AO_Init works non-blocking. Callback function IOExt_AOInitCallback is triggered if command has finished and AO channel on C3 extension module was selected (extSerial >= 0).

Command may be used within a command sequence. See Command Sequence Usage for more information.

IOExt_AOInitCallback(serial, chnl, result)

Analog output channel init completed (Callback for IOCtrl_AO_Init(), C3 IO Extension)

serial : u32 - serial number of the extension module

chnl : u8 - AO Channel

result : s32 - Resultcode

OK: AO channel init was successful
ERROR: any error occured

IOCtrl_AO_Close(chnl, extSerial=-1)

Close analog output channel

chnl : u8 - Output channel

extSerial : s32 - serial number of the extension module, -1 if not used

returns : s32

OK - Command accepted

ERROR_NOT_SUPPORTED - Function not available, IO Controller firmware probably not up to date

ERROR - If one of the following errors occurs

IO controller command is currently not allowed (init, reset, shutdown or update is in progress).

Command queue is full.

Command sequence is full.

Function works non-blocking. No dedicated callback function is used if command has finished.

IOCtrl_AO_SetValue(chnl, value, extSerial=-1)

Set analog output value

chnl : u8 - Output channel

value : u16 - Output value, [uA] for mA Output modes (see AO_MODE)

extSerial : s32 - serial number of the extension module, -1 if not used

returns : s32

OK - Command accepted

ERROR_NOT_SUPPORTED - Function not available, IO Controller firmware probably not up to date

ERROR - If one of the following errors occurs

IO controller command is currently not allowed (init, reset, shutdown or update is in progress).

Command queue is full.

Command sequence is full.

IOCtrl_AO_SetValue works non-blocking. Callback function IOExt_AOSetValueCallback is triggered if command has finished and AO channel on C3 extension module was selected (extSerial >= 0).

Command may be used within a command sequence. See Command Sequence Usage for more information.

IOExt_AOSetValueCallback(serial, chnl, result, value)

Process which sets the analog output value was completed (Callback for IOCtrl_AO_SetValue(), C3 IO Extension)

serial : u32 - serial number of the extension module

chnl : u8 - AO Channel

result : s32 - Resultcode

OK: Setting update value was successful
ERROR: any error occured

value : u16 - Output value, [uA] for mA Output modes (see AO_MODE)

IOCtrl_AO_GetStat(chnl, extSerial=-1)

Get analog output status

chnl : s32 - Output channel, -1 to select all channels

extSerial : s32 - serial number of the extension module, -1 if not used

returns : s32

OK - Command accepted

ERROR_NOT_SUPPORTED - Function not available, IO Controller firmware probably not up to date

ERROR - If one of the following errors occurs

IO controller command is currently not allowed (init, reset, shutdown or update is in progress).

Command queue is full.

Command sequence is full.

IOCtrl_AO_GetStat works non-blocking. Callback function IOExt_AOGetStatCallback is triggered if command has finished and AO channel on C3 extension module was selected (extSerial >= 0).

Command may be used within a command sequence. See Command Sequence Usage for more information.

IOExt_AOGetStatCallback(serial, chnl, stat)

Analog output status is available (Callback for IOCtrl_AO_GetStat(), C3 IO Extension)

serial : u32 - serial number of the extension module

chnl : u8 - AO Channel

stat : u8 - Output status, see AO_STAT definitions

Abstract:

The C3 IO extension modules must be connected with the C3 main module via CAN interface. On top of the physical CAN interface the higher level protocol CANopen is used. The CAN interface (including CANopen) is fully managed internally (at 1MBit bitrate) and is not available for the application program in this mode. The appropriate mode for the CAN interface is automatically selected by calling IOExt_Init. All API functions use the serial number of the extension module for addressing. The serial number is printed on the label. If a extension module is ready to operate, the function assigned to IOExt_ReadyCallback is called. For UI, DigOut and SysValues no new API functions are available, a new (optional) parameter extSerial was added.

The CAN termination resistors must be set properly for every extension module. The switches are at the bottom of the module. Please see the device documentation for more information.

All connected extension modules will be reset automatically from C3 base module if a restart of the rapidM2M C3xx itself was detected. This will happen if a new DLO is loaded or a rapidM2M C3xx firmware update was performed.

IOEXT_STATE:

Device States for IO extension modules

IOEXT_STATE_NOT_FOUND - 0

Module is not available

IOEXT_STATE_INIT - 1

Init is in progress

IOEXT_STATE_OK - 2

Ready to operate

IOEXT_STATE_ERROR - 3

Any error occured (e.g. CAN bus error)

IOExt_Init()

Prepare for C3 IO Extension usage

returns : s32 - Result

OK: command accepted
ERROR_NOT_SUPPORTED: IO Controller firmware probably not up to date
ERROR: any other error occured

The CAN interface will be switched to internal mode (CANopen) for interfacing C3 IO Extension modules. The CAN interface is not available for the application program in this mode. This function must be called prior to any other function related to extension modules.

IOExt_ReadyCallback(serial, sId[TIOCtrl_Id])

IO Extension Ready (Callback for IOExt_Init() )

serial - serial number of the extension module

sId[TIOCtrl_Id] - IO Extension ID information

Function is called automatically if IO Extension module changed to READY state.

After activating CAN interface (see IOExt_Init)
After powering module
After module firmware update

IOExt_ErrorCallback(serial)

IO Extension Error (Callback for IOExt_Init() )

serial - serial number of the extension module

Function is called automatically if IO Extension module changed to ERROR state. The IO Controller firmware monitors all connected IO Extension modules. ERROR state is entered if a response timeout is detected. This is probably caused by any CAN bus physical layer problem (e.g. wiring error, termination resistors not configured properly, ...)

IOExt_GetState(serial)

Read current device state

serial - serial number of the extension module

returns : s32

OK - Command accepted

ERROR - If one of the following errors occurs

IOExt_StateCallback not activated. Check your Library Config.

IO controller command is currently not allowed (init, reset, shutdown or update is in progress).

Command queue is full.

Command sequence is full.

Function works non-blocking. The device state will be passed to the function IOExt_StateCallback.

Command may be used within a command sequence. See Command Sequence Usage for more information.

IOExt_StateCallback(serial, extState)

Current device state of a extension module is available (Callback for IOExt_GetState() )

serial - serial number of the extension module

extState - current device state, see IOEXT_STATE

IOExt_GetId(serial)

Read ID information

serial - serial number of the extension module

returns : s32

OK - Command accepted

ERROR - If one of the following errors occurs

IOExt_IDCallback not activated. Check your Library Config.

IO controller command is currently not allowed (init, reset, shutdown or update is in progress).

Command queue is full.

Function works non-blocking. ID information will be passed to the function IOExt_IDCallback.

IOExt_IDCallback(serial, sId[TIOCtrl_Id])

ID information of a extension module is available (Callback Function for IOExt_GetId() )

serial - serial number of the extension module

sId - ID information

IOExt_GetFwInfo(serial)

Read Firmware Info

serial - serial number of the extension module

returns : s32

OK - Command accepted

ERROR - If one of the following errors occurs

IOExt_FwInfoCallback not activated. Check your Library Config.

IO controller command is currently not allowed (init, reset, shutdown or update is in progress).

Command queue is full.

Command sequence is full.

This function provides the information for the firmware that is currently active. Function works non-blocking. Firmware information will be passed to the function IOExt_FwInfoCallback.

Command may be used within a command sequence. See Command Sequence Usage for more information.

IOExt_FwInfoCallback(serial, sInfo[TIOCtrl_FwInfo])

Firmware information of a extension module is available (Callback for IOExt_GetFwInfo() )

serial - serial number of the extension module

sInfo - Firmware Information

IOExt_EnableDowngrade()

Enable IO Extension firmware downgrades

IO Extension updates are not triggered automatically, therefore for each IO Extension IOExt_Update() has to be called.

returns : s32

OK - Downgrades enabled

ERROR_NOT_SUPPORTED - Downgrades not enabled (IO Controller FW < 01v006)

IOExt_DisableDowngrade()

Disable IO Extension firmware downgrades

IOExt_Update(serial)

Trigger firmware update

If the firmware update was successful, the AppLog entry "MT_MODFWUPDATED" is generated. The parameter specifies the serial number of the extension module that was updated.

If no update has been performed, the AppLog entry "MT_MODFWUPDATED" is created where the parameter indicates the serial number of the extension module and the reason why it has not been updated.

serial - serial number of the extension module

returns : s32 - OK if command accepted, otherwise ERROR

Function works non-blocking. Status information will be passed to the function IOExt_UpdateCallback. The updatefile is transferred from the rapidM2M C3xx to the selected extension module first (DOWNLOAD phase). Afterwards the update process itself is started (INSTALL phase).

IOExt_UpdateCallback(serial, res)

IO Controller firmware update Process for a extension module completed (Callback for IOExt_Update() )

serial - serial number of the extension module

res - Resultcode

OK - Firmware update was successful

OK+1 - Firmware update in progress (BUSY)

ERROR - General error during firmware update

C3_ERROR_FW_OLD_VERSION - see C3_ERROR_x

C3_ERROR_FW_SAME_VERSION - see C3_ERROR_x

CommandSequenceAbstract:

Several commands can be grouped together to a command sequence. This functionality is useful to reduce traffic on the IO Controllers SPI/UART interface.

There are two different command sequence modes, "single" and "multiple".

Single

The command sequence is directly sent to the IO Controller after it is built and is NOT persistent. I.e. it cannot be sent to the IO controller again later in the same form. This command sequences mode is suitable for sequenzes that are only required once (e.g. initialization procedure of an UI channel).

A new "single" command sequence is initiated with the IOCtrl_SeqEnterSingle() function. IO controller commands (e.g. IOCtrl_UI_Init()) can then be added. With the Function IOCtrl_SeqExitAndSendSingle(), the command sequence is completed and immediately sent to the IO Controller.

Multiple

"Multiple" command sequences are persistent after being built. Therefore it is not necessary to rebuild the sequence every time, before sending the sequence.

So "multiple" command sequences are suitable for sequenzes that are to be sent repeatedly in the same form to the IO Controller (e.g. reading out the UI channels in the measurement interval).

A new "multiple" command sequence is initiated with the IOCtrl_SeqEnterMultiple() function. IO controller commands (e.g. IOCtrl_UI_GetValue()) can then be added. With the Function IOCtrl_SeqExitMultiple(), the command sequence is completed. To send the command sequence to the IO Controller, the function IOCtrl_SeqSendMultiple() must be called. Since "multiple" command sequences are persistent after creation, the command sequence can be repeatedly sent to the IO Controller using the IOCtrl_SeqSendMultiple() function. This means that it is not necessary to recreate the command sequence every time. When created, a unique ID is assigned to the "multiple" command sequence that can be used to distinguish the individual sequences when sending them to the IO Controller.

The "Command Sequence" functionality can be enabled by setting IOCTRL_N_CMDSEQ to a value > 0. If enabled the size of the "Command Queue" (IOCTRL_LEN_CMD_QUEUE) can be reduced since several commands can be combined to a "Command Sequence". The number of "Command Sequences" that can be created simultaneously can be specified via IOCTRL_N_CMDSEQ. The size of the buffer (in bytes) available for a individual "Command Sequence" is specified via IOCTRL_CMDSEQ_DATA_LEN.

Memory required for the "Command Sequence" functionality: IOCTRL_N_CMDSEQ * IOCTRL_CMDSEQ_DATA_LEN Bytes

Not all IO Controller commands can be added to a "Command Sequence", it is mentioned in the several function descriptions.

Command Sequence Usage:

Single Mode

/* Enters "single" command sequence mode: * The following commands will not be added to the default command queue, * they will be buffered within the next free command sequence list */ IOCtrl_SeqEnterSingle(); /* Adds commands for initializing 3 UI channels to sequence list */ IOCtrl_UI_Init(0, UI_CHT_SI_DIGITAL); IOCtrl_UI_Init(1, UI_CHT_SI_DIGITAL); IOCtrl_UI_Init(2, UI_CHT_SI_DIGITAL); /* Exits "single" command sequence mode: * Normal command mode (send immediately through command queue) will be * activated again. The previous commands are stored within the sequence * list and the resulting sequence will be sent. After sending, * the currently used command sequence list is released again. */ IOCtrl_SeqExitAndSendSingle();

Multiple Mode

/* Enters "multiple" command sequence mode using 0 as the unique ID for the sequence. * The following commands will not be added to the default command queue, * they will be buffered within command sequence list with ID 0. */ IOCtrl_SeqEnterMultiple(0); /* Adds commands for reading out the IO Controller system values and * the current UI channel values to the command sequence list with the ID 0 */ IOCtrl_GetSysValues(); IOCtrl_UI_GetValue(); /* Exits "multiple" command sequence mode: * Normal command mode (send immediately through command queue) will be * activated again. The previous commands are stored within the * command sequence list with ID 0 and the command sequence list with ID 0 is ready to send. */ IOCtrl_SeqExitMultiple(0); /* Sends the command sequence list with unique ID 0 */ IOCtrl_SeqSendMultiple(0);

IOCTRL_N_CMDSEQ -

Number of "Command Sequences" that can be created simultaneously

IOCTRL_CMDSEQ_DATA_LEN -

Size of the buffer (in bytes) available for a individual "Command Sequence"

IOCtrl_SeqEnterSingle()

Enters "single" command sequence mode

The next free command sequence list will be initialized and prepared for building a new "single" command sequence.

See CommandSequenceAbstract for more information on the "single" command sequence mode.

returns : s32 - Result

OK - Sequence mode "single" entered successfully

ERROR_NOT_SUPPORTED - IO Controller firmware probably not up to date

ERROR-1 - No free command sequence list currently available

If this error is encountered frequently, try to increase the number of "Command Sequences" that can be created simultaneously (using IOCTRL_N_CMDSEQ)

ERROR - If one of the following error occurs

Another command sequence is currently being built

Command sequencing not activated (i.e. IOCTRL_N_CMDSEQ not set)

IOCtrl_SeqExitAndSendSingle()

Exits "single" command sequence mode and directly sends the built sequence

The sequence built in "single" mode is reset after sending and can not be sent again.

returns : s32 - Result

OK - Completing and sending of the "single" command sequence was successful

ERROR_NOT_SUPPORTED - IO Controller firmware probably not up to date

ERROR - If one of the following error occurs

Tried to exit "multiple" command sequence mode (i.e. instead of "single" command sequence mode, "multiple" command sequence mode is currently active)

Command sequencing not activated (i.e. IOCTRL_N_CMDSEQ not set)

Command queue full (try to increase the size of the command queue, via IOCTRL_LEN_CMD_QUEUE)

Another internal error occured

IOCtrl_SeqEnterMultiple(id)

Enters "multiple" command sequence mode

The command sequence list selected via "id" (Sequence List identifier) will be initialized/reset and prepared for building a new "multiple" command sequence.

See CommandSequenceAbstract for more information on the "multiple" command sequence mode.

id - Sequence List identifier (>=0, freely selectable)

returns : s32 - Result

OK - Sequence mode "multiple" entered successfully

ERROR_NOT_SUPPORTED - IO Controller firmware probably not up to date

ERROR-1 - The selected command sequence list is currently not available (BUSY)

If this error is encountered frequently, try to increase the number of "Command Sequences" that can be created simultaneously (using IOCTRL_N_CMDSEQ).

ERROR - If one of the following error occurs

Another command sequence is currently being built

Invalid Sequence List identifier (i.e. negative value for "id" passed).

Command sequencing not activated (i.e. IOCTRL_N_CMDSEQ not set)

IOCtrl_SeqExitMultiple(id)

Exits "multiple" command sequence mode

Completes the command sequence list that was started to be built with the last call of the IOCtrl_SeqEnterMultiple() function. The built "multiple" command sequence is ready to be sent (using IOCtrl_SeqSendMultiple()).

id - Sequence List identifier (>=0, must correspond to the value used when starting to build the command sequence)

returns : s32 - Result

OK - Sequence built successfully

ERROR - If one of the following error occurs

Invalid Sequence List identifier (i.e. negative value for "id" passed).

Passed Sequence List identifier does not correspond to the value used when starting to build the command sequence using the IOCtrl_SeqEnterMultiple() function.

Tried to exit "single" command sequence mode (i.e. instead of "multiple" command sequence mode, "single" command sequence mode is currently active)

Command sequencing not activated (i.e. IOCTRL_N_CMDSEQ not set)

Another internal error occured

IOCtrl_SeqSendMultiple(id)

Sends a specific prebuilt "multiple" command sequence which is selected via "id" (Sequence List identifier. Specified when the "multiple" command sequence was created using IOCtrl_SeqEnterMultiple() )

Command is not accepted if command sequence mode is currently active. i.e. command sequence mode has been entered using IOCtrl_SeqEnterMultiple() or IOCtrl_SeqEnterSingle() but not yet exited using IOCtrl_SeqExitMultiple() or IOCtrl_SeqExitAndSendSingle().

id - Sequence List identifier (>=0, must correspond to a value used when starting to build a command sequence)

returns : s32 - Result

OK - Sequence sending command accepted

ERROR_NOT_SUPPORTED - IO Controller firmware probably not up to date

ERROR-1 - Sending the "multiple" command sequence is not possible because the selected sequence is currently being executed (BUSY).

ERROR - If one of the following error occurs

Invalid Sequence List identifier (i.e. negative value for "id" passed).

Unknown Sequence List identifier (Passed "id" was not used to create a "multiple" command sequence using the IOCtrl_SeqEnterMultiple() function)

Command sequence mode has been entered (i.e. A command sequence is currently being built. Complete the command sequence by calling IOCtrl_SeqExitMultiple() or IOCtrl_SeqExitAndSendSingle()).

Another internal error occured

C3_Shutdown(timeout=0)

Make a clean shutdown with IO Controller shutdown, closing CAN, RS232 and RS485 interfaces.

Although this function will still be supported for the purpose of downward compatibility, it should no longer be used for new projects. The C3_TriggerShutdown() function should be used as an alternative.

timeout - optional; default=0; time till rM2M is turned off

If the rM2M is transmitting the timeout is set to at least 120 seconds else to at least 10 seconds.

IOCtrl_SeqModeEnter(id)

Enter sequence mode

The selected command sequence list will be initialized/reset and prepared for building a new command sequence.

Although this function will still be supported for the purpose of downward compatibility, it should no longer be used for new projects. The IOCtrl_SeqEnterMultiple() function should be used as an alternative.

id - Sequence List identifier

returns : s32 - Result

OK: successful
ERROR_NOT_SUPPORTED: IO Controller firmware probably not up to date
ERROR-1: The selected command sequence list is currently not available (BUSY)
ERROR: any other error occured

IOCtrl_SeqModeExit(id)

Exit sequence mode

Finish selected command sequence list. Command sequence can be sent with IOCtrl_SeqCmd(id) afterwards.

Although this function will still be supported for the purpose of downward compatibility, it should no longer be used for new projects. The IOCtrl_SeqExitMultiple() function should be used as an alternative.

id - Sequence List identifier

returns : s32 - Result

OK: command accepted
ERROR: any other error occured

IOCtrl_SeqCmd(id)

Send sequence command

Although this function will still be supported for the purpose of downward compatibility, it should no longer be used for new projects. The IOCtrl_SeqSendMultiple() function should be used as an alternative.

id - Sequence List identifier

returns : s32 - Result

OK: command accepted
ERROR_NOT_SUPPORTED: IO Controller firmware probably not up to date
ERROR-1: The selected command sequence list is already pending (BUSY)
ERROR: any other error occured

Command is not accepted if command sequence mode is currently active. See IOCtrl_SeqModeEnter(id) and IOCtrl_SeqModeExit(id).

Libraries

rapidM2M C3xx Base

Description

Supported rapidM2M devices:

OVERVIEW

Supported rapidM2M devices:

rapidM2M C3xx

Generell information regarding the IO Controller

Universal inputs

RS232 interface

RS485 interface

CAN interface

Digital outputs

Shutdown handling

C3 IO Extension Modules

Generell information regarding the IO Extensions

Universal inputs (only for C3e 12UI/2Rel)

Digital outputs

Analog outputs (only for C3e 3mA/6Rel)

Shutdown Handling procedure:

EXPERT

COMMON

Shutdown handling procedure

Firmware Update Errors

IO Controller Init Errors

Shutdown Handling Errors

SHUTDOWN HANDLING

Button and LED

FILES

UI

UI TRIGGER

RS232

Prepare RS232 for use:

RS485

Prepare RS485 for use:

CAN

Prepare CAN for use:

DIGOUT

AO - Analog Out

IO Extension

COMMAND SEQUENCES

Single

Multiple

Single Mode

Multiple Mode

Deprecated

On this page

rapidM2M C3xx Base