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|lincan]] and [[LinCAN|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 (DINFO) 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 Communication Components V2 deliverable][oceraD74].
  82 But it is quite dated and not fully complete, same for some code features.
  83 The basic CAN part and river has been in production use and is tested
  84 and documented in separate file.
  85 Because OCERA project code base is not maintained as whole for
  86 some time, we are in process of separation of the parts which
  87 have been maintained and has potential for future.
  88
  89 As for OCERA CANopen stuff, it has been designed as highly dynamic
  90 with possibility to mimic different hardware devices and to develop
  91 complete CANopen master to build dictionary proxies to multiple
  92 devices for multiple higher level clients. The base infrastructure
  93 is laid out, we use canblaster to access devices dictionaries
  94 from Java based CANmonitor and to analyze CAN traffic from Qt based tool.
  95
  96 On the device side, the capability to mimic device dictionary according
  97 to EDS file is implemented. The HDS is additional description,
  98 which allows to load shared libraries (DLLs) and map object dictionary
  99 objects into generic CANopen device binary. This way it is possible
 100 to add new I/O capability without need to rebuild base binary.
 101 The HDS file maps object dictionary index and subindex to named
 102 data I/O descriptor DINFOs which are exported by shared library
 103 object. You can find example of implementation of such module
 104 in the file
 105
 106     ortcan-top/app/candev/nascanhw/nascanhw.c
 107
 108 The "nascanhw.so" implements two integer I/O variables (DINFOs)
 109 "input01" and "output01" which are connected together to copy
 110 "input01" to "output01" variable. The copy action is then notified
 111 back into "canslave" generic code. This allow to even map these object
 112 into PDOs and request to sent PDO when the mapped object values changes.
 113 The "hardware" provided variables are mapped into object dictionary by device
 114 (Hardware Description File) HDS. The "nascan.hds" is simple example,
 115 which interconnects the first digital outputs group with with
 116 the first digital inputs group for DS401 profile device.
 117
 118     6000:01 /nascanhw/input01
 119     6200:01 /nascanhw/output01
 120
 121 You can test most of build components by script
 122
 123     ./test-can-in-konsole
 124
 125 The script  test native build of [[LinCAN|lincan]] in the KDE konsole window.
 126 This script uses command DCOP scripting capabilities of konsole
 127 and if it is started from already running console, scripting has
 128 to be enabled.
 129
 130 Parameter "--script" is required when konsole has been started.
 131
 132     konsole --script
 133
 134 You can run individual commands by hand as well.
 135
 136 As for whole OrtCAN CANopen implementation, I believe still,
 137 that it is right way to go to have something generic with possibility
 138 to integrate into SCICOS or Matlab-Simulink models. There is potential,
 139 but we have not found project to fund some faster progress
 140 in the attempt. Basic CANopen infrastructure works but mapping
 141 is updated only when device is switched from and back to CANopen
 142 OPERATIONAL state.
 143
 144 The full implementation of all PDO time triggered transfers modes
 145 is missing.
 146
 147 On the other hand for simple applications, [CANfestival](http://sourceforge.net/projects/canfestival/)
 148 is probably faster and simpler implementation.
 149 There are some examples of its use in other project of our department
 150 <http://dce.felk.cvut.cz/waszniowski/>.
 151 On the other hand, if application is expected to be runtime configurable,
 152 then OrtCAN approach is better suited for such use. CANfestival is not
 153 prepared nor intended to allow dynamic dictionary operations.
 154
 155 ## Time Triggerred CANopen PDO Messages
 156
 157 The VCA code places infrastructure there, but not all features
 158 are finished. It is waiting to some spare time, project funding,
 159 students diploma thesis work or contributors.
 160
 161 The PDO can be sent as response to the source value change notification
 162 over event connectors. This is tested, works and is probably most
 163 complicated mode if that should be done without polling.
 164 The SYNC driven and time driven modes needs to be implemented.
 165 The function \_pdo_hub_event() should be divided into part processed
 166 at variable change notification, which only marks fields requiring
 167 update and PDO should be moved on list of Tx PDOs which require
 168 more processing. The second part should do real update and sending.
 169 Then PDO processor should take PDO from the list, update it and send
 170 it to the CAN bus. SYNC response would mean only connecting
 171 of SYNC filer and new rx_hub on PDO processor through
 172 vcaNet_msg_rec_connect(). SYNC processing would mean only marking PDO
 173 as requiring to be sent. Each PDO should contain timer field and then
 174 periodic mode could be implemented as marking PDO to be sent
 175 in timer call-back.
 176
 177 The function vcaPDOProcessor_processMsg() is alternative to use
 178 of the full vcaNet_msg_rec_connect() infrastructure.
 179 So yes, above mentioned functionality of marking
 180 SYNC triggered PDOs for Tx could be added there.
 181 The key is to refactor \_pdo_hub_event() function and addition
 182 of list for PDOs with pending requests.
 183
 184 [omk]:http://rtime.felk.cvut.cz/omk/
 185 [socketcan]:http://developer.berlios.de/projects/socketcan/
 186 [oceraD74]:http://www.ocera.org/download/documents/deliverables/ms4-month24.html