PAM Serial Line
PAM Serial Line
TABLE OF CONTENTS
1 INTRODUCTION 1
4 CONFIGURATION PHASE 8
Table of Contents I
Technical Manual 006.8021.C PAM SOCAPEL SA
6 EXECUTION PHASE 20
9 APPLICATION PROTOCOL 30
II Table of Contents
SOCAPEL SA PAM Technical Manual 006.8021.C
12 COMMUNICATION CONFIGURATION 53
IV Table of Contents
SOCAPEL SA PAM Technical Manual 006.8021.C
1 INTRODUCTION
The RS422 serial communication channel allow to exchange variables between PAM and the RS422
Master.
The RS422 variables must be allocated in both PAM and RS422 Master memory.
In the PAM application language RS422 variables get a name, but to exchange variable value trough
the RS422 serial communication channel a KEY value is more fast and easy to use. The values of
these keys are exchanged during the configuration phase using the CRC value of the variable
definition in order to identify the variable. The KEY is a "user" reference, it can be the address of a
memory location, the index of an array, etc...
The communication protocol define the blocks protocol and the application protocol. The aim is to
exchange variable value in both direction.
1.1.2 ID OF A VARIABLE
The PAM compiler affect an ID value for each PAM object, the ID value range from 0 to n
for each main class of object ( for example INTERNAL variables or RS422 variables)
The value of the ID is function of the position of the declared name in the application source
file. In PAM, objects are accessed only in using the ID value.
If the user system support C language, the user may use the RS422 C utilities and examples to write
this software. If not, the user need to implement management of blocks and application protocol
with respect of protocol definitions.
• Communication request.
• Configuration phase ( exchange of variables definitions).
• Execution phase ( exchange of variables values).
The PAM RS422 C utilities provide for the user all the functions needed for communication
request, configuration phase and the exchange of variable value during execution phase. Protocols
details at blocks level and application level, are hidden by the PAM RS422 utilities.
The RS422 utilities need to call some low level function in order to send and receive characters
trough the RS422 serial communication port.
The RS422 utilities need to call some application level function in order to update user variables.
The PAM RS422 C utilities is a library of C functions, designed to hide protocol details and to be
easy to use in order to realise the configuration phase and execution phase.
PAM\RS422\RS_UTIL
PAM\RS422\RS_USER
PAM\RS422\AGL
The .sub directory\RS_UTIL contents the main part of the RS422 C utilities
!
Some functions have been modified in order to handel 32 bits unsigned integer
timouts
The .sub directory \RS_USER contents C files that show how to use functions of the RS422
utilities. You will also find a PC executable files (PC_DEMO.EXE ). To check RS422 link you
may run the PC_DEMO after having loading into PAM the application that you will find in the sub
directory \AGL.
The file USR_COMM.H (given by Socapel) define the functions prototypes used to interface the
PAM RS422 Utilities with the RS422 communication port (hardware dependant)
The user must implement the body of the functions describe in the USR_COMM.H file.
The file USR_FUNC.H (given by Socapel) define the functions prototypes used to interface the
PAM RS422 Utilities with the application level of the user software.
These functions allow to access the RS422 user's variable from the PAM RS422 utilities.
The user must implement the body of the functions describe in the USR_FUNC.H file.
Remark : in order to implement these functions the user need to create a kind of variables database.
This database must be accessed from some user functions, but if the user want to store the "RS422
software" in EPROM, the RS422 software must not be linked with the database, because the
database is application dependant.
The file PAMRS422.H depends of the application and is automatically generated during
execution of PAMCOMP.
This file is generated into the \AGL sub directory of the compiled application.
This file contents the CRC value corresponding to the variable declaration, the variable
identifier is used to give a name to the CRC value. We use the #define directive of the pre-
processor for C language :
The file RS_CLASS.H depends of the PAM system version and defines the classes value of
RS422 variables.
The file RS_UTIL.H contents all the struct definitions and functions prototype of the PAM
RS422 C utilities.
The file RS_UTIL.C contents all the body of functions of the PAM RS422 C utilities.
This file and, sub files attached, must be compiled and linked with all other files of the user
software.
4 CONFIGURATION PHASE
The declaration of RS422 variables at PAM application language level contents the identifier (or
name) of the variable, the type of the variable and the number of items of the variable.
On the RS422 master side, the variables must also be declared. The aim of the configuration phase
is to check if both declarations match and to exchange and store the KEY value of each variable.
To allow to identify a variable in order to check the declaration we use the CRC value. The CRC is
a number computed by the PAMCOMP compiler, using a 16 bits cyclic redundancy check applied
to all items of the variable declaration (name, type, size,...).
These CRC values are given in a include file for C programming language. The user must use these
CRC values to establish a list that make the relation between the CRC identifier and user
information on the user implementation of the variable corresponding to the PAM RS422 variable.
For each input variable, the RS422 master must ask PAM to send to it the KEY value used by
PAM for this input. PAM send also the CRC value, class, number of items, ... to allow
checking.
The master have to store the receved KEY value for use in execution phase and also if master
need to send the initial value of the variable. ( the initial value is to be sent if non zero).
REMARK : the value of the ID are given into the .DOC file
EXAMPLE :
For each output variable, the RS422 master must send to PAM the KEY value used by the
RS422 master for this output. PAM send also the CRC value, class, number of items, ... to
allow checking.
PAM store the KEY value for use during the execution phase.
This function initialise the messages queue and memorise send and receive buffer size. The size of
buffer must be the same value used by the function that initilise the port.
The disconnect_timeout in [ms ] ( reception timeout for execution phase) is memorised.
The cycle_time in [ms] is memorised.
Before using the function init_pam_rs422_util, the user must initialise the RS422
! communication port and allocate the communication buffers.
The timeout_value [ms] is the time during which the master try to get the
communication with PAM
WARNING This function call the user function :
extern void rs422_user_system_call(int16 cycle_time);
The function rs422_user_system_call (whose function prototype is given by file
USR_FUNC.H ) is needed to wait answer and to be able to manage a time out.
-->
<--
The timeout_value [ms] is the time used to declare that there is no answer from PAM, we
recommand a value of 5000 ms.
typedef struct {
usint8 sub_code;
usint16 crc;
usint16 lsw_key;
usint16 msw_key;
} s_config_cmd ;
typedef struct {
usint8 sub_code;
usint16 crc;
usint16 pam_key;
usint8 var_class /* class of the variable (PAM class value) */
usint8 item_nb /* max items of multiple variable */
} s_config_answ ;
LIST OF COMMAND SUB CODE VALUE:
RS_ASK_DEF_VAR 1 master ask PAM to send one RS422 definition.
RS_DEF_OUT_KEY16 2 master send one definition of output for PAM
(16 bits Key).
RS_DEF_OUT_KEY32 3 master send one definition of output for PAM
(32 bits Key).
RS_BEG_INIT_IN 4 master start to send initial value of some inputs
RS_START 5 master request PAM to start RS422 normal handling.
RS_START_AND_UPDATE_OUT 6 master request PAM to send all outputs value and
start RS422 normal handling.
The RS422 master must send command RS_ASK_DEF_VAR until PAM acknowledge
RS_END_DEF_VAR.
For each definition the master must check if the given CRC value exist in its own list.
When CRC do not match, PAM have extra variables.
When CRC match, if master have fixed reservation, check of class and number of items must be
done.
For input with not matching definition, the RS422 master must cancel this input by using -1 for key
value, error may be reported but master must continue the configuration.
When all match, master store the input key.
For Output with not matching definition, the RS422 master must tag this output in order to avoid to
send later the key of this output.
PAM ACTION :
MASTER ACTION :
When RS422 master receive the answer RS_END_DEF_VAR, it must check in its own list if extra
variable definition remain.
OR
RS_BAD_OUT_CRC <-- PAM
The RS422 master send all the output keys that are present in its own list.
When the master get the answer RS_DEF_OUT_ANSW, the master may initialise the output value
to 0 and send the next definition.
When master receive RS_BAD_OUT_CRC : error may be reported and master send the next
definition.
The master send a command RS_BEG_INIT_IN or RS_START to signalise the end of output keys
definition !
When PAM receive command RS_BEG_INIT_IN or RS_START, it must check in its own list if
extra output definition remain. The key value of these extra definitions are set to -1 to cancel them.
No error are displayed.
The master sends initial values of inputs using the stantard exchange variable functions !
Normal answer
RS_INIT_IN_OK <-- PAM
When PAM receive the command RS_BEG_INIT_IN, PAM answer RS_INIT_IN_OK and wait for
exchange variable commands, PAM don't answer to the exchange variable command.
The master must send a RS_START command to tell PAM that there no more initial value for
inputs.
PAM answer
RS_STARTED <-- PAM
Master Action :
PAM action :
Answers RS_STARTED if all phases of configuration are done, then PAM start to write into
OUTPUT FIFO new value of OUTPUTS, start to scan input fifo and PAM start the watch dog
handling.
Send RS_START_REFUSED if configuration phases are missing, and display error [0700003D],
but PAM try to continue working.
During the disconnection of the serial line, the PAM application continue working and may
internally update RS422 output variables.
When the MASTER connects again to PAM, the configuration phase do not reset the value of
outputs as the first configuration after PAM power up do. This leads to a situation where
value of outputs may be different between PAM and Master.
D1 : given class
D2 : PAM class
D3 : 0
6 EXECUTION PHASE
The watch dog message must be sent if no other message as been sent during approximatively "n"
ms. The "n" value is specified by the PAM_WATCHDOG_MESSAGE_PERIOD parameter.
Disconnection is detected if no message received during approximately "t" ms. The "t" value is
specified by the MASTER_INACTIVITY_TIMEOUT parameter.
t
According with n ≤
2
This value must be greater than the time of inactivity required to send watch dog message.
These values are given on PAM side as parameters of the RS422 declaration in the application.
The cyclically called function scan_rs422_pam_out perform watch dog handling on master side.
If the fatal error is a ring broken error, PAM is still able to answer a COMM_REQ from
MASTER and to start the configuration phase. But when the execution phase starts, because
of the fatal error, PAM do not send any messages. So this situation leads to an endless
connection requested from MASTER and disconnection by PAM.
To avoid the mentioned situation, PAM, in case of fatal error do not answer to COMM_REQ
command.
The parameters of these functions take care of the multiple variable handling capability of PAM.
The access code is a parameter that define how the contents of multiple variables must be accessed:
The function scan_rs422_pam_out contents a loop that call the block sender and
i block receiver a number of time that correspond to the given cycle_time value divide
by 2
This to have a block production and consommtion indepandant of the duration of the
user cycle.
User working with concurrent operating system may modify the scan_rs422_pam_out
i function and make call from concurrent routine to block sender and block receiver.
In order to update user's variables, this function need to call the following user funtions :
============================
RS422 communication error !
============================
< 16 bits CRC> : Cyclic Redundancy check applied application message (2 bytes,
first = lsb )
In the case of bad block received the content of the block is lost, and there no special procedure for
repeating the block.
The above considerations show us that in case of exchange of messages in both direction using the
maximum capability of the RS422 channel, if the receiver need to send the Xoff char., the free
space of the input buffer must be in the worst case : size of output buffer + "near full" size of input
buffer of the other system.
We can conclude that it is not possible to dimension the buffer size for the worst case !
9 APPLICATION PROTOCOL
The application protocol describes the content of the application message. The message contents at
least a function code. The content of the message depends of the function code.
The PAM RS422 C Utilities hides all the details of this protocol, except for some function codes the
user have to know for the configuration phase.
The examples given with the RS422 C utilities will show the usage of all functions.
Remarks : PAM use the XNG_xxxx_KEY32 to send outputs to the master if the msw of the key
value is non zero. The PAM key is always 16 bits.
This way of weighting the bytes is corresponding to the C compiler implementation when
using for example an union.
typedef union {
unsigned char bytes[4];
long value;
} u_key_4 ;
with:
u_key_4 test = 0x12345678 we get :
test.bytes[0] = 0x78, test.bytes[1] = 0x56, test.bytes[2] = 0x34, test.bytes[3] = 0x12
Message structure with sub code RS_START_AND_UPDATE_OUT:
[0]
cod&sub
3 ][ 6
Messages
Receiver
COMM.
HANDLER
Messages To Send and
pointer queue
Messages
Sender
Insert Xoff
TX driver
W
TX
1024 Char Output Buffer
RX
R
Messages
Receiver
COMM.
HANDLER
Messages To Send and
pointer queue
Stop to send
Messages
Sender
TX driver
W
TX
1024 Char Output Buffer
HOST PAM
Input buffer Input buffer
R W W R
Read Xoff
and Stop to send
Output buffer Output buffer
R R
W Xoff W
Buffers situation
HOBS = Host Output Buffer Size POBS = Pam Output Buffer size
HIBS = Host Input Buffer Size PIBS = Pam Input Buffer Size
HNFR = Host Near Full Ratio PNFR = Pam Near Full Ratio
Number of characters still received by Host when Host send Xoff (worst case)
NRH = HOBS + (PIBS * PNFR)
NRH = 1024 + (1024 * 0.75) = 1792
REMARK:
It is only possible to adapt the input buffer size for PAM or for HOST, but not for both.
Because Host Input Buffer Size (HIBS) is dependant of PAM Input Buffer Size (PIBS) and
PIBS is dependant of HIBS.
! It is not easy to modify the buffers size when using Greenleaf communication utility
It is not possible to manage Xoff & Xoff at char level when using Greenleaf
! communication utility
HOST PAM
Send watch Master
dog period Inactivity
Timeout
PAM
Inactivity
Watch dog
Timeout message period
Watchdog mechanism.
12 COMMUNICATION CONFIGURATION
To be able to communicate with PAM, a plug-in module must be added on the PAM board and the
RS422 port connector assignement must be configured by jumpers.
The communication parameters (baud rate, parity, NB of bits) must be configured in accordance
with PAM.
2 RECEIVE -
3 TRANSMIT +
7 RECEIVE +
8 TRANSMIT -
• Parity OFF
• Stop bit 1
• Data bits 8
• 19200 bauds for BASIC_PAM_CYCLE = 3 ( 1 ms cycle)
/*-----*/
/* crc */
/*=====*/
{
/* Allocate a buffer */
char *buffer = new (char[255]) ;
if ( !buffer )
passert(0) ;
/* CRC computation*/
returns string_CRC (buffer) ;
} /* crc */
REMARK:
The way of creating the string on which the crc16 computation is applied was not designed to
be used as a user function.
This algorithm may be subject to change in order to simplify and make easier the string
composition by external user.
CRC16 COMPUTATION:
The CRC16 computation used is the same as furnished with the RS422 utilities.
Refer to file CRC_UTIL.C for computation algorithm.
INDEX
TYPE_DEF.H 7
USR_COMM.H 6
A USR_FUNC.H 6
Function
Application Protocol 30
get_pam_rs422_comm 10
init_pam_rs422_util 10
B scan_rs422_pam_out 24
send_rs422_flag 22
baud rate 54 send_rs422_long 22
Blocks Protocol 28 send_rs422_real 22
send_rs422_single_flag 22
send_rs422_single_long 22
C send_rs422_single_real 22
Communication send_rs422_single_word 22
configuration 53 send_rs422_word 22
parameters 54 xchng_config_cmd 11
Protocol 28
Request 10 H
Configuration
Error messages 18 Handling of
Jumpers 53 Inputs by PAM 20
Configuration of Inputs by RS422 master 20
Input Variables 8 Outputs by PAM 20
Output Variables 9 Outputs by RS422 master 20
Configuration phase 8 Hardware configuration 53
Connector 54
M
E
Message
Exchange of COMM_ACK 31
Output KEY 14 COMM_REQ 31
Variable definition 12 CONFIG_ANSW 34
Execution Phase 20 CONFIG_CMD 32
Execution Phase Errors 25 RS_WATCH_DOG 35
XNG_FLAG 36
XNG_FLAG_KEY32 41
F XNG_LONG 38
Files XNG_LONG_KEY32 43
Overwiew 5 XNG_REAL 39
PAMRS422.H 6 XNG_REAL_KEY32 45
RS_CLASS.H 7 XNG_WORD 37
RS_COMM 7 XNG_WORD_KEY32 42
RS_UTIL 7 Module 004.7025 53
Database 6
P ID 1
KEY 1
Protocol 28; 30
Name 1
S W
Starting PAM 16
Watchdog 21; 51
T X
timeouts 51
Xoff 29; 47
Xon 29; 47
V
Variable
CRC 1
ii Index