(no commit message)

[ortcan-www.git] / vca / index.mdwn

diff --git a/vca/index.mdwn b/vca/index.mdwn
index 9b61b14d061f2c379bb073942ae1c74bf9a2930f..fde94cffb425c92436983f3d95d752af611ffee1 100644 (file)
--- a/vca/index.mdwn
+++ b/vca/index.mdwn
@@ -1,19 +1,87 @@
 [[!meta title="libVCA (OrtCAN Virtual/Versatile CAN API library)"]]
 
 The library providing common API for CAN/CANopen bus protocol.
 [[!meta title="libVCA (OrtCAN Virtual/Versatile CAN API library)"]]
 
 The library providing common API for CAN/CANopen bus protocol.

-It can be used with [[LinCAN|lincan]] and [SocketCAN](http://developer.berlios.de/projects/socketcan/)
+It can be used with [[LinCAN|lincan]] and [SocketCAN][socketcan]

 Linux drivers. The CANopen part can be used as base for
 implementation of CANopen devices as well as CANopen
 master/monitor nodes.
 
 Linux drivers. The CANopen part can be used as base for
 implementation of CANopen devices as well as CANopen
 master/monitor nodes.
 

+## VCA Library Quick Build Instructions
+
+The build from GIT repository is recomended. The next commands are used to obtain
+sources
+
+    git clone git://git.code.sf.net/p/ortcan/ortcan-top
+    cd ortcan/
+    git submodule update --init
+    make default-config
+
+The build components selection and configuration is controlled by "config.omk"
+file which overrides "config.omk-default". The default sources configuration
+builds VCA support for [[LinCAN|lincan]] and [[LinCAN|lincan]] driver is build as well.
+The option for building library sources relinkable into shared objects (DLLs)
+is required for example modules building on x86_64 and PowerPC targets
+
+    echo 'CFLAGS+=-fpic' >>config.omk
+
+Next configuration options should be specified in "config.omk" file
+to build VCA library with [SocketCAN][socketcan] support only
+
+    CONFIG_OC_LINCAN=n
+    CONFIG_OC_ULUTKERN=n
+    CONFIG_OC_CANVCA_IFC=socketcan
+
+The VCA library can be build even with runtime selectable CAN bus
+access support. This is enabled by option "multi" and list of
+interfaces which are compiled into library
+
+    CONFIG_OC_CANVCA_IFC=multi
+    CONFIG_OC_CANVCA_IFC_lincan=y
+    CONFIG_OC_CANVCA_IFC_socketcan=y
+
+The whole tree of sources includes generic CANopen slave
+device implementation ("canslave" executable) which mimics
+standard CANopen nodes implemented by dedicated hardware.
+The OD (CANopen Object Dictionary) is specified at program
+startup by specifying which standard EDS file should be
+parsed to build index and subindex structures of OD.
+The build is controlled by next "config.omk" option
+
+    CONFIG_OC_CANDEV=y
+
+The "canslave" executable can be used not only to provide
+OD behavior for CAN bus remote access but can be used
+without need of recompilation to connect OD data
+with real or simulated hardware data sources. The connection
+is realized by specifying interconnection between
+OD index and subindex entries and named data access
+information structures (DINFO) provided by loadable
+modules. Example of simple example of such module which
+provides two mutually interconnected data items is provided
+in "app/candev/nascanhw/nascanhw.c" source file which is
+build into "libnascanhw.so" module. The build of that example
+module is controlled by next "config.omk" line
+
+    CONFIG_OC_CANSLAVE_NASCANHW=y
+
+The actual build of the libVCA is specified GNU make program
+invocation
+
+    make
+
+The result binaries are found in "\_compiled/bin" after successfull
+build. More information about possible make targets provided
+by underlaying [OMK make system][omk] can be found on its [home page][omk].
+

 ## VCA CANopen Functionality
 
 ### Standard EDS and VCA Hardware Connection Configuration HDS Files
 
 The most comprehensive OCERA RT CAN/CANopen components documentation
 ## VCA CANopen Functionality
 
 ### Standard EDS and VCA Hardware Connection Configuration HDS Files
 
 The most comprehensive OCERA RT CAN/CANopen components documentation

-is part of WP7.4 deliverable. But it is quite dated and not fully
-complete, same for some code features. The basic CAN part and river
-has been in production use and is tested and documented in separate file.
+is part of [WP7.4 Communication Components V2 deliverable][oceraD74].
+But it is quite dated and not fully complete, same for some code features.
+The basic CAN part and river has been in production use and is tested
+and documented in separate file.

 Because OCERA project code base is not maintained as whole for
 some time, we are in process of separation of the parts which
 have been maintained and has potential for future.
 Because OCERA project code base is not maintained as whole for
 some time, we are in process of separation of the parts which
 have been maintained and has potential for future.


@@ -29,7 +97,7 @@ On the device side, the capability to mimic device dictionary according
 to EDS file is implemented. The HDS is additional description,
 which allows to load shared libraries (DLLs) and map object dictionary
 objects into generic CANopen device binary. This way it is possible
 to EDS file is implemented. The HDS is additional description,
 which allows to load shared libraries (DLLs) and map object dictionary
 objects into generic CANopen device binary. This way it is possible

-add new I/O capability without need to rebuild base binary.
+to add new I/O capability without need to rebuild base binary.

 The HDS file maps object dictionary index and subindex to named
 data I/O descriptor DINFOs which are exported by shared library
 object. You can find example of implementation of such module
 The HDS file maps object dictionary index and subindex to named
 data I/O descriptor DINFOs which are exported by shared library
 object. You can find example of implementation of such module


@@ -41,19 +109,20 @@ The "nascanhw.so" implements two integer I/O variables (DINFOs)
 "input01" and "output01" which are connected together to copy
 "input01" to "output01" variable. The copy action is then notified
 back into "canslave" generic code. This allow to even map these object
 "input01" and "output01" which are connected together to copy
 "input01" to "output01" variable. The copy action is then notified
 back into "canslave" generic code. This allow to even map these object

-into PDOs and request to sent PDO on its values changes. The "hardware"
-provided variables are mapped into object dictionary by device
+into PDOs and request to sent PDO when the mapped object values changes.
+The "hardware" provided variables are mapped into object dictionary by device

 (Hardware Description File) HDS. The "nascan.hds" is simple example,
 which interconnects the first digital outputs group with with
 the first digital inputs group for DS401 profile device.
 
 (Hardware Description File) HDS. The "nascan.hds" is simple example,
 which interconnects the first digital outputs group with with
 the first digital inputs group for DS401 profile device.
 

-    6000:01 /nascanhw/input01 6200:01 /nascanhw/output01
+    6000:01 /nascanhw/input01
+    6200:01 /nascanhw/output01

 
 You can test most of build components by script
 
     ./test-can-in-konsole
 
 
 You can test most of build components by script
 
     ./test-can-in-konsole
 

-The script  test native build of LinCAN in the KDE konsole window.
+The script  test native build of [[LinCAN|lincan]] in the KDE konsole window.

 This script uses command DCOP scripting capabilities of konsole
 and if it is started from already running console, scripting has
 to be enabled.
 This script uses command DCOP scripting capabilities of konsole
 and if it is started from already running console, scripting has
 to be enabled.


@@ -77,10 +146,10 @@ is missing.
 
 On the other hand for simple applications, [CANfestival](http://sourceforge.net/projects/canfestival/)
 is probably faster and simpler implementation.
 
 On the other hand for simple applications, [CANfestival](http://sourceforge.net/projects/canfestival/)
 is probably faster and simpler implementation.

-There are some examples of its use in other project of our department
-<http://dce.felk.cvut.cz/waszniowski/>.
-On the other hand, if application is expected to be runtime configurable,
-then OrtCAN approach is better suited for such use. CANfestival is not
+There are some examples of its use together with Matlab and Real-Time Workshop
+in other [projects][hil_ydc] lead by Libor Waszniowski.
+But that approach has limited support for runtime configurable applications
+and for such cases the OrtCAN approach is better suited. CANfestival is not

 prepared nor intended to allow dynamic dictionary operations.
 
 ## Time Triggerred CANopen PDO Messages 
 prepared nor intended to allow dynamic dictionary operations.
 
 ## Time Triggerred CANopen PDO Messages 


@@ -91,9 +160,9 @@ students diploma thesis work or contributors.
 
 The PDO can be sent as response to the source value change notification
 over event connectors. This is tested, works and is probably most
 
 The PDO can be sent as response to the source value change notification
 over event connectors. This is tested, works and is probably most

-complicated mode if should be done without polling.
+complicated mode if that should be done without polling.

 The SYNC driven and time driven modes needs to be implemented.
 The SYNC driven and time driven modes needs to be implemented.

-The function _pdo_hub_event() should be divided into part processed
+The function \_pdo_hub_event() should be divided into part processed

 at variable change notification, which only marks fields requiring
 update and PDO should be moved on list of Tx PDOs which require
 more processing. The second part should do real update and sending.
 at variable change notification, which only marks fields requiring
 update and PDO should be moved on list of Tx PDOs which require
 more processing. The second part should do real update and sending.


@@ -109,5 +178,10 @@ The function vcaPDOProcessor_processMsg() is alternative to use
 of the full vcaNet_msg_rec_connect() infrastructure.
 So yes, above mentioned functionality of marking
 SYNC triggered PDOs for Tx could be added there.
 of the full vcaNet_msg_rec_connect() infrastructure.
 So yes, above mentioned functionality of marking
 SYNC triggered PDOs for Tx could be added there.

-The key is to refactor _pdo_hub_event() function and addition
+The key is to refactor \_pdo_hub_event() function and addition

 of list for PDOs with pending requests.
 of list for PDOs with pending requests.

+
+[omk]:http://rtime.felk.cvut.cz/omk/
+[socketcan]:http://developer.berlios.de/projects/socketcan/
+[oceraD74]:http://www.ocera.org/download/documents/deliverables/ms4-month24.html
+[hil_ydc]:http://support.dce.felk.cvut.cz/pub/xwasznio/HIL_YDC/HIL_YDC.htm