vca/index.mdwn

   1 [[!meta title="libVCA (OrtCAN Virtual/Versatile CAN API library)"]]
   2
   3 The library providing common API for CAN/CANopen bus protocol.
   4 It can be used with [[LinCAN|lincan]] and [SocketCAN][socketcan]
   5 Linux drivers. The CANopen part can be used as base for
   6 implementation of CANopen devices as well as CANopen
   7 master/monitor nodes.
   8
   9 ## VCA Library Quick Build Instructions
  10
  11 The build from GIT repository is recomended. The next commands are used to obtain
  12 sources
  13
  14     git clone git://ortcan.git.sourceforge.net/gitroot/ortcan/ortcan
  15     cd ortcan/
  16     git submodule update --init
  17     make default-config
  18
  19 The build components selection and configuration is controlled by "config.omk"
  20 file which overrides "config.omk-default". The default sources configuration
  21 builds VCA support for LinCAN and LinCAN driver is build as well.
  22 The option for building library sources relinkable into shared objects (DLLs)
  23 is required for example modules building on x86_64 and PowerPC targets
  24
  25     echo 'CFLAGS+=-fpic' >>config.omk
  26
  27 Next configuration options should be specified in "config.omk" file
  28 to build VCA library with [SocketCAN][socketcan] support only
  29
  30     CONFIG_OC_LINCAN=n
  31     CONFIG_OC_ULUTKERN=n
  32     CONFIG_OC_CANVCA_IFC=socketcan
  33
  34 The VCA library can be build even with runtime selectable CAN bus
  35 access support. This is enabled by option "multi" and list of
  36 interfaces which are compiled into library
  37
  38     CONFIG_OC_CANVCA_IFC=multi
  39     CONFIG_OC_CANVCA_IFC_lincan=y
  40     CONFIG_OC_CANVCA_IFC_socketcan=y
  41
  42 The whole tree of sources includes generic CANopen slave
  43 device implementation ("canslave" executable) which mimics
  44 standard CANopen nodes implemented by dedicated hardware.
  45 The OD (CANopen Object Dictionary) is specified at program
  46 startup by specifying which standard EDS file should be
  47 parsed to build index and subindex structures of OD.
  48 The build is controlled by next "config.omk" option
  49
  50     CONFIG_OC_CANDEV=y
  51
  52 The "canslave" executable can be used not only to provide
  53 OD behavior for CAN bus remote access but can be used
  54 without need of recompilation to connect OD data
  55 with real or simulated hardware data sources. The connection
  56 is realized by specifying interconnection between
  57 OD index and subindex entries and named data access
  58 information structures (DIONFO) provided by loadable
  59 modules. Example of simple example of such module which
  60 provides two mutually interconnected data items is provided
  61 in "app/candev/nascanhw/nascanhw.c" source file which is
  62 build into "libnascanhw.so" module. The build of that example
  63 module is controlled by next "config.omk" line
  64
  65     CONFIG_OC_CANSLAVE_NASCANHW=y
  66
  67 The actual build of the libVCA is specified GNu make program
  68 invocation
  69
  70     make
  71
  72 The result binaries are found in "\_compiled/bin" after successfull
  73 build. More information about possible make targets provided
  74 by underlaying [OMK make system][omk] can be found on its [home page][omk].
  75
  76 ## VCA CANopen Functionality
  77
  78 ### Standard EDS and VCA Hardware Connection Configuration HDS Files
  79
  80 The most comprehensive OCERA RT CAN/CANopen components documentation
  81 is part of WP7.4 deliverable. But it is quite dated and not fully
  82 complete, same for some code features. The basic CAN part and river
  83 has been in production use and is tested and documented in separate file.
  84 Because OCERA project code base is not maintained as whole for
  85 some time, we are in process of separation of the parts which
  86 have been maintained and has potential for future.
  87
  88 As for OCERA CANopen stuff, it has been designed as highly dynamic
  89 with possibility to mimic different hardware devices and to develop
  90 complete CANopen master to build dictionary proxies to multiple
  91 devices for multiple higher level clients. The base infrastructure
  92 is laid out, we use canblaster to access devices dictionaries
  93 from Java based CANmonitor and to analyze CAN traffic from Qt based tool.
  94
  95 On the device side, the capability to mimic device dictionary according
  96 to EDS file is implemented. The HDS is additional description,
  97 which allows to load shared libraries (DLLs) and map object dictionary
  98 objects into generic CANopen device binary. This way it is possible
  99 add new I/O capability without need to rebuild base binary.
 100 The HDS file maps object dictionary index and subindex to named
 101 data I/O descriptor DINFOs which are exported by shared library
 102 object. You can find example of implementation of such module
 103 in the file
 104
 105     ortcan-top/app/candev/nascanhw/nascanhw.c
 106
 107 The "nascanhw.so" implements two integer I/O variables (DINFOs)
 108 "input01" and "output01" which are connected together to copy
 109 "input01" to "output01" variable. The copy action is then notified
 110 back into "canslave" generic code. This allow to even map these object
 111 into PDOs and request to sent PDO on its values changes. The "hardware"
 112 provided variables are mapped into object dictionary by device
 113 (Hardware Description File) HDS. The "nascan.hds" is simple example,
 114 which interconnects the first digital outputs group with with
 115 the first digital inputs group for DS401 profile device.
 116
 117     6000:01 /nascanhw/input01 6200:01 /nascanhw/output01
 118
 119 You can test most of build components by script
 120
 121     ./test-can-in-konsole
 122
 123 The script  test native build of LinCAN in the KDE konsole window.
 124 This script uses command DCOP scripting capabilities of konsole
 125 and if it is started from already running console, scripting has
 126 to be enabled.
 127
 128 Parameter "--script" is required when konsole has been started.
 129
 130     konsole --script
 131
 132 You can run individual commands by hand as well.
 133
 134 As for whole OrtCAN CANopen implementation, I believe still,
 135 that it is right way to go to have something generic with possibility
 136 to integrate into SCICOS or Matlab-Simulink models. There is potential,
 137 but we have not found project to fund some faster progress
 138 in the attempt. Basic CANopen infrastructure works but mapping
 139 is updated only when device is switched from and back to CANopen
 140 OPERATIONAL state.
 141
 142 The full implementation of all PDO time triggered transfers modes
 143 is missing.
 144
 145 On the other hand for simple applications, [CANfestival](http://sourceforge.net/projects/canfestival/)
 146 is probably faster and simpler implementation.
 147 There are some examples of its use in other project of our department
 148 <http://dce.felk.cvut.cz/waszniowski/>.
 149 On the other hand, if application is expected to be runtime configurable,
 150 then OrtCAN approach is better suited for such use. CANfestival is not
 151 prepared nor intended to allow dynamic dictionary operations.
 152
 153 ## Time Triggerred CANopen PDO Messages
 154
 155 The VCA code places infrastructure there, but not all features
 156 are finished. It is waiting to some spare time, project funding,
 157 students diploma thesis work or contributors.
 158
 159 The PDO can be sent as response to the source value change notification
 160 over event connectors. This is tested, works and is probably most
 161 complicated mode if should be done without polling.
 162 The SYNC driven and time driven modes needs to be implemented.
 163 The function \_pdo_hub_event() should be divided into part processed
 164 at variable change notification, which only marks fields requiring
 165 update and PDO should be moved on list of Tx PDOs which require
 166 more processing. The second part should do real update and sending.
 167 Then PDO processor should take PDO from the list, update it and send
 168 it to the CAN bus. SYNC response would mean only connecting
 169 of SYNC filer and new rx_hub on PDO processor through
 170 vcaNet_msg_rec_connect(). SYNC processing would mean only marking PDO
 171 as requiring to be sent. Each PDO should contain timer field and then
 172 periodic mode could be implemented as marking PDO to be sent
 173 in timer call-back.
 174
 175 The function vcaPDOProcessor_processMsg() is alternative to use
 176 of the full vcaNet_msg_rec_connect() infrastructure.
 177 So yes, above mentioned functionality of marking
 178 SYNC triggered PDOs for Tx could be added there.
 179 The key is to refactor \_pdo_hub_event() function and addition
 180 of list for PDOs with pending requests.
 181
 182 [omk]:http://rtime.felk.cvut.cz/omk/
 183 [socketcan]:http://developer.berlios.de/projects/socketcan/