(04) Theory : Driver

Contents

Requirements
API or Driver
The layered driver model
Data flow
The ComDrv classes
A simple driver

Driver requirements

Handle communication with peripheral device

Depends on the protocol only, not on the specific device
May handle any number of datapoints of any type
Performs conversion and smoothing

Driver info

How does a driver know

What values to send?

Where to send them to?

How to send them?

How to handle received data?

Answer: Driver specific configs

_address

_smooth, _cmd_conv, _msg_conv

Driver configs

Distribution Config (Event manager)

Specifies Driver Number

Address Config (Driver)

Reference (Address String)

Subindex

Transport Direction and - Mode

Transformation

Address config

Address configs tell the driver

What datapoints are of interest


Where to find the hardware value


How to transform between WinCC OA Variables
and hardware representation


and much more...

Example of an address mapping

PLC
DB0

DB1

DW2
...

DB3

Valve

DW0
DW1

DB2

WinCC OA

DB1DW1

Cmd
Rm
State
Value
DB1DW1

Example for Address Mapping

Variables in SPS
identified by Index

Address string identifies
KR and IX

Profibus SPS identified
by KR

Conversion configs

Conversion configs tell the driver, how to

convert Raw Value <--> Eng. Value

Polynom 4th degree

Spline
Logarithms
and more...

Smoothing configs

Smoothing configs tell the driver, when not to

send values

Compare old and new value

Compare the time received
Flutter suppression
and more...

10

Modularity

Modularity

WinCC OA Data
Conversion and
Smoothing
Software Protocol,
Telegram Layer
HW Protocol, Kernel
Driver

WinCC OA

Smoothing

Conversion

Transformation

Old/New

HW
11

Other tasks

Communication tasks

Interface configuration and initialisation

(Re) connect to device
Bi-directional data conversion
(High Level) Conversion and smoothing
Connection state supervision

12

Other tasks

WinCC OA Communication tasks

(Re) connect to Event manager

(Re) connect to output datapoints

Error logging and protocol

13

Driver compared to API

Use API when

There is only one (or few) device type

Each device can be represented by
a specific DP type
But: There is no API device class

14

Driver compared to API

Use Driver when

There are different device types

There is no easy match between DPE and HW
The device values are represented by any DPE
Most work is done in the ComDrv classes

15

WinCC OA Driver

HW independent

WinCC OA
Parameterization

Request /Response

Polling

Message conversion

Connection administr.

Command conversion

HW dependant

Mapper

Smoothing

Mapping of periphery address to hardware address

Transformation

HWService

Hardware Interface:
general query

Command

Single query

Spontaneous notification

Periphery
16

ComDrv classes

HWMapper
DrvManager
Communication

DP Lookup

DrvDpCont

Transformation

Configs, Conversion

HWService
Hardware

SPS
17

ComDrv Classes: DrvManager

Handle Communication with Event manager

General processing of read- and write commands
and notifications (call of appropriate classes)
Derive your own class from DrvManager to install
your helper classes

18

ComDrv Classes: DrvDpCont

Container for the driver specific configs

Handle smoothing and conversion (configs)
Handle transformation between raw values and
WinCC OA Variables via transformation classes.
Usually not derived by specific driver

19

ComDrv Classes: Transformation

Transformation between raw value and WinCC OA

Variable representation
Called from the DrvDpCont class
One specific class needed for each data type
Each config contains a transformation object.

20

ComDrv Classes: HWMapper

Maps DPE to HW address

Manages lists DpId <--> Address config to

access Configs either by name or by DpId
Manages lists WinCC OA <--> HW address to
convert between logical address (name) and
real address (any format)
N configs with same name and different subix
correspond to one HW address

21

HWMapper lists
WinCC OA

HWMapDpPa

DpId

Addr

Your part
N

HWObject

Addr

HW

22

HWMapper Access Functions

Search for HWObject

findHWObject: Search by HW-Address

findHWAddr: Search by WinCC OA-Address
getFirstComponentIndex(HWObject *): Search by
HW-Address and component
get4Component(HWObject *, long idx): Iterate
over HWObject for one component

23

HWMapper Access Functions

Search for DpId / Configs

getFirstIndex(HWObject *) Index of config with

lowest subindex with matching name
getConfigPtr([HWObject *, ] long idx)
Get config at position idx.
Optional: Only if the name matches

24

HWMapper Update Functions

Update Lists

addDpPa: Called for new configs

clrDpPa: Called for deleted configs
addHWObject: Call to add a new HWObject
clrHWObject: Call to remove an HWObject

Derive your own class to keep the lists in

sync

25

HWService

The main interface class for your hardware protocol implementation

initialize()

init hardware, ComDrv is initialized

start()

start communication, EV is connected

stop()

stop communication

workProc()

check for incoming data from hardware

(use DrvManager::toDP() for sending to WinCC OA)

writeData()

WinCC OA wants you to send data

singleQuery()

WinCC OA wants you to poll a value

generalQuery()

WinCC OA wants you to request all values

26

ComDrv Classes: HWObject

HWObject: Transport of data, contains:

Address name and Subindex

Data buffer with raw values
Number of elements in buffer
Transformation type, origin type, origin time, ...

Derive your own HWObject for additional infos

needed by the hardware protocol

Deduce the hardware address from the address name

27

HWObject entries

Can be created due to WinCC OA side configuration

For each new config in addDpPa create corresponding HWObject and

insert it into HWMapper
For each removed config in ClrDpPa remove corresponding HWObject
from HWMapper
Take care for multiple input parametrization!

Can be due to external parametrization or hardware information

During HWService::initialize() or HWService::start() get list of available

objects and create corresponding HWObjects in HWMapper

28

Data Flow in the ComDrv

Send value to peripheral device

Receive Hotlink and for each item do:

Lookup address config of DP or father

Lookup address config with subix 0
(HWMapper::getFirstIndex)

Set-up a HWObject
(HWMapper::findAddrObj)

Convert to raw data
(Transformation::toPeriph)

Send all values (HWService::writeData)

Signal all groups done (HWService::flush)
29

Data Flow in the ComDrv

Receive data from device

ComDrv calls HWService::workProc

You recv. data and set-up HWObject dataObj
with HW address, subix of first value, data and
number of elements
You lookup address object addrObj in HWMapper
(HWMapper::findHWObject)
You call DrvManager::toDp(dataObj, adrObj)

30

Data Flow in the ComDrv

Receive data (cont.)

Lookup address config with subix 0

(HWMapper::getFirstIndex)
Check LowLevelComparision
With LLC break data down to chunks, else
process entire buffer
(DrvManager::processData2Dp)

31

Data Flow in the ComDrv

Receive data (cont.)

Lookup all DpId and address config within

range [subix...+nofElements]
(HWMapper::getConfigPtr)
For each config, thats not an output do:

Convert data to WinCC OA (Transformation::toVar)

Convert and smooth

Collect all those data

Send data to Event
(DrvManager::sendData2Dp)

32

Data Flow in the ComDrv

Request data from device (SQ, Polling)

Lookup address config for DpId (SQ only)

Lookup address config with subix 0
(HWMapper::getFirstIndex)
Set-up HWObject with address and subix
(HWMapper::findHWAddr)
ComDrv calls HWService::singleQuery
You request Data and send them to
DrvManager::toDp

33

General Program Flow

mainLoop

Dispatch (GQ, SQ, send data to device)

Request polled data
Call HWService::workProc to poll device
Send data to Event
Cont. with dispatch

34

ComDrv Class Overview

Most of the work is done inside the ComDrv

classes

DrvManager communicates with Data, Event and

has the overall control
DrvDpCont manages the driver configs and is
responsible for data conversion and smoothing
HWMapper manages the lists to map the WinCC
OA address to a hardware address

35

ComDrv is an application!

ComDrv is a fully grown manager with its own config entries and
internal datapoint for runtime control

Config file entries are listed in the WinCC OA online reference

drvDpName defines the name of the ComDrv control DP

defaults to _Driver_num
...

Config file entries all have default values, so normally there is no

need to use the ComDrv config entries

36

ComDrv is an application!

ComDrv internal datapoint is used for runtime control

.GQ
.SQ
.PM
.DC
.AD.HWMask
.AD.DPMatch
.HW.HWMask
.HW.HWMatch
.IGQ

trigger general query

trigger single query
set poll mode (on/off)
disable commands (for redundancy)
search mask for periphaddress
all datapoints matching this mask
search mask for hwaddress
all hwaddresses which match
trigger general query on WinCC OA side

37

ComDrv Classes Overview cont.

Helper classes assist

HWMapDpPa contains the mapping DpId and

address config
PollList and PollItem manage the polling list
HWObject transport data, map address name to
hardware address and store last values for LLC
DrvAlive is a multipurpose timer class

38

ComDrv Helps You

PeriphAddr:

The address config

getName, getSubindex: Get name (_reference)

and subindex (_subindex)
getTransform, getTransformType: Get the
transformation object / type (_datatype)
setTransform, setTransformType: Set the
transformation object / type
isOutput, isSingle: Direction is to device, items
are transmitted individually (_mode)

39

ComDrv Needs Your Help

Transformation: Transform data between

WinCC OA variables and hardware format

toPeriph, toVar: Convert data WinCC OA <--> HW

isA: Define your own type
itemSize: HW size in byte of one value
getNumberOfElements: nofEl in one item
getVariableType: Optional, specify your favourite
WinCC OA variable type for toPeriph

40

ComDrv Needs Your Help

HWService: Interface for ComDrv

initialise, start, stop: Initialise interface, connect /

disconnect to device
workProc: poll peripheral devices
writeData: Send data to device
singleQuery: Request data from device
generalQuery: Request all data from device

41

ComDrv Needs Your Help

DrvRsrce: Manages config file and internal

datapoints

init, readSection: read config file

getNumberOfDpNames, getDpName4Query,
setDpIdentifier: Internal DP-name resolution
getNumberOfIdsToConnect, getId2Connect,
answer4DpId: Connect to internal DP
HWService::hotLink2Internal: Internal DP HL

42

Managing Internal DP

Define the DP name at the end of DrvRsrce::init

function

Get the DpId for internal DP

ComDrv calls DrvRsrce::getNumberOfDpNames

Return the number of Elements of your internal DP
For each DPE ComDrv calls getDpName4Query
Set-up an return the DPE name
For each response from Data Driver calls
DrvRsrce::setDpIdentifier
Driver calls DrvRsrce::allIdsGot, until you return TRUE
Then Driver connects to Event
43

ComDrv Needs Your Help

Connect

to internal DP

Driver calls DrvRsrce::getNumberOfIdsToConnect

For each DP Driver calls DrvRsrce::getId2Connect

For each answer Driver calls DrvRsrce::answer4DpId
At least delete the varPtr

Driver calls DrvRsrce::ready2Connect until you return
TRUE. Return TRUE if you got all current values you need
for initialisation, else FALSE

For each hotlink Driver calls DrvRsrce::isInternalDpID
Return INTERNAL_DPID, if its your internal DP, else
NOT_INTERNAL_DPID

44

ComDrv Needs Your Help

Notifications for internal DP

For each hotlink Driver calls DrvRsrce::isInternalDpID

Return INTERNAL_DPID, if its your internal DP, else
NOT_INTERNAL_DPID
Driver calls HWService::hotLink4InternalDp, if its your
internal DpId (above calls returned INTERNAL_DPID)

45

ComDrv needs your help

Since version 3.9 new DrvIntDp class

Easy support for internal datapoints

Most functionality implemented transparent to user

Specify number of DPEs

Overload callback functions

getName4DpId
answer4DpId
hotLink2Internal

46

(User)bits

Data quality bits

HWObject->setSBit(...)
DRV_USERBIT1 .... DRV_USERBIT32
DRV_INVALID

Userbit assignment
should be configurable via
config file entries!

HWObject->setTimeOfPeriphFlag()

Source of data

HWObject->setObjSrcType(...)

srcSpont
srcPolled
srcSingleQ
srcGeneralQ

47

Use of sub-indexes

Use sub-indexes if you cant distinguish items by

their HW address only
e.g. the 8 bits in a byte

If possible all items with identical address shall be

transmitted (Output Group)

Or they shall always be transmitted one at a time

(Output Single).

48

Use of sub-indexes: Altogether

In HWMapper::addDpPa

Check that there is only one HWObject for all
configs (N : 1)

(re) calculate the buffer length for all items and
set nofElement, Dlen in the HWObject

You may safely use LLC

Call DrvManager::toDp with this HWObject as

the second argument

49

Use of sub-indexes: Singles

In HWMapper::addDpPa

You may add one HWObject for each config (1:1) or

one for all configs (1:N)
(re) calculate the buffer length for all items and set
nofElement, Dlen in the HWObject
You may safely use LLC only if you have one
HWObject per config (data is stored there)

Call DrvManager::toDp with the correct

HWObject (Subindex) as second argument

50

Use of sub-indexes: Mixed

You dont want to go the easy way, or?

For Output: Check, if config is for Single or Group
and do as shown before

For Input: Behave as if all items will come together.
LLC will work after all items were transmitted together
the first time.

51

Redundancy

Redundancy is handled by the ComDrv

_DriverCommon.DC disables sending commands for

non-internal DPs

When receiving commands from your own internal DP

check the DC-state
(DrvResources::getDisableCommands()

Send input data from device to Event as if you were not

redundant

52

Redundancy

copyDp

Ctrl

EV

EV

Ctrl

fwdDp

Drv

Drv

53