manual.tex

CANopen 协议栈源码 ,实现基本的CANopen 协议

\begin{verbatim}
	--target=hcs12
\end{verbatim}

To do a \canopen node running on a microncontroller Motorola MC9S12DP256,
you need :

\begin{enumerate}
\item The compiler GNU gcc for HC11, HC12, HCS12 : m6811 -elf. \\
 Download the \textbf{release 3.1} at : \href{http://m68hc11.serveftp.org/m68hc11_pkg_rpm.php}{http://m68hc11.serveftp.org/m68hc11\_pkg\_rpm.php} 
\item A board with this chip. We are using the T -board from Electronikladen. 
\item At least about 40 kBytes of program memory. 
\item A tool to flash the memory. (We are using the high cost Lauterbach
debugger). 
\end{enumerate}

\subsection{Running a HCS12 node}


\subsubsection{Compiling Canfestival:}

\begin{verbatim}
	./configure --target=hcs12
\end{verbatim}


\subsubsection{Compiling and building an example}

Enter in the folder of an HCS12 example,

\begin{verbatim}
	make all
\end{verbatim}


\subsubsection{Flashing the memory :}

Use your preferred loader ! If you are using a debugger Lauterbach,
you can load the bash file : trace32\_flash\_programmer.cmm. It loads
directly the elf file.


\subsubsection{Connecting to a serial RS232 console :}

Connect the portS(TxD0) of the HCS12 to a console configured at 19200
bauds 8N1, via a Max232 chip to adapt the electrical levels. On Linux,
you can use minicom. Connecting to a console is useful to read the
messages, but not required.


\subsubsection{Connecting to the CAN network :}

Connect the port CAN0 (pin PM0, PM1) to the network via a CAN controller.
On our board, the CAN controller is a PCA82C250 chip.


\subsubsection{starting the node :}

Press the reset of your HCS12 board.


\section{Example and test program:}

The {}``examples'' directory contains some test program you can
use as example for your own developments.


\subsection{TestMasterSlave}


\begin{verbatim}
  **************************************************************
  *  TestMasterSlave                                           *
  *                                                            *
  *  A simple example for PC. It does implement 2 CanOpen      *
  *  nodes in the same process. A master and a slave. Both     *
  *  communicate together, exchanging periodically NMT, SYNC,  *
  *  SDO and PDO. Master configure heartbeat producer time     *
  *  at 1000 ms for slave node-id 0x02 by concise DCF.         *                                  
  *                                                            *
  *   Usage:                                                   *
  *   ./TestMasterSlave  [OPTIONS]                             *
  *                                                            *
  *   OPTIONS:                                                 *
  *     -l : Can library ["libcanfestival_can_virtual.so"]     *
  *                                                            *
  *    Slave:                                                  *
  *     -s : bus name ["0"]                                    *
  *     -S : 1M,500K,250K,125K,100K,50K,20K,10K,none(disable)  *
  *                                                            *
  *    Master:                                                 *
  *     -m : bus name ["1"]                                    *
  *     -M : 1M,500K,250K,125K,100K,50K,20K,10K,none(disable)  *
  *                                                            *
  **************************************************************
\end{verbatim}


Notes aboute use of voncise DCF :

In this example, Master configure heartbeat producer time
at 1000 ms for slave node -id 0x02 by concise DCF according DS -302
profile.

Index 0x1F22, sub-index 0x00 of the master OD, correspond
to the number of entries. This equal to the maximum possible nodeId
(127). Each sub -index points to the Node -ID of the device, to which
the configuration belongs.

To add more parameters configurations to the slave, the value
at sub -index 0x02 must be a binary stream (little -endian) following
this structure :


\begin{verbatim}

	 (UNS32) nb of entries
	 (UNS16) index parameter 1
	 (UNS8) sub -index parameter 1
	 (UNS32) size data parameter 1
	 (DOMAIN) data parameter 1
	 (UNS16) index parameter 2
	 (UNS8) sub -index parameter 2
	 (UNS32) size data parameter 2
	 (DOMAIN) data parameter 2
	      ....
	 (UNS16) index parameter n
	 (UNS8) sub -index parameter n
	 (UNS32) size data parameter n
	 (DOMAIN) data parameter n
	 
\end{verbatim}


So the binary value stream to configure heartbeat producer
time must be :


\begin{verbatim}
	0100000017100002000000e803
\end{verbatim}


The slave node is configured just before the Master entering
in Pre\_operational state.


\subsection{gene\_SYNC\_HCS12 :}

This is a simple \canopen node that only send cyclic SYNC message.
It demonstrate implementation on HCS12 based board.

\bigskip{}



\subsection{kerneltest :}

Example based on TestMasterSlave slightly modified to suit kernel
space requisites. It will do the same as TestMasterSlave but in kernel
space sending kernel messages (displayed by dmesg for example). It
is designed as external kernel module implemented as character device.
There is a shell script called 'insert.sh', which will insert the
module and create a new device file /dev/canf\_ktest (used to sending
commands to module). To actual sending commands you can use simple
console named 'canf\_ktest\_console'. The module is dependent on a
another separate module 'canfestival.ko' implementing CanOpen stack
which exports requisite functions. Canfestival.ko module is then dependent
on CAN card driver module, by default CAN virtual driver will be loaded.
After installing modules (make install), all dependencies are solved
automatically by kernel. To run the example type: 
\begin{verbatim}
	sh run.sh
\end{verbatim}
It will insert required modules, start console, and after quitting
console it'll remove modules from kernel.

\bigskip{}



\subsection{TestMasterMicroMod }



\begin{verbatim}
  **************************************************************
  *  TestMasterMicroMod                                        *
  *                                                            *
  *  A simple example for PC.                                  *
  *  A CanOpen master that control a MicroMod module:          *
  *  - setup module TPDO 1 transmit type                       *
  *  - setup module RPDO 1 transmit type                       *
  *  - setup module hearbeatbeat period                        *
  *  - disable others TPDOs                                    *
  *  - set state to operational                                *
  *  - send periodic SYNC                                      *
  *  - send periodic RPDO 1 to Micromod (digital output)       *
  *  - listen Micromod's TPDO 1 (digital input)                *
  *  - Mapping RPDO 1 bit per bit (digital input)              *
  *                                                            *
  *   Usage:                                                   *
  *   ./TestMasterMicroMod  [OPTIONS]                          *
  *                                                            *
  *   OPTIONS:                                                 *
  *     -l : Can library ["libcanfestival_can_virtual.so"]     *
  *                                                            *
  *    Slave:                                                  *
  *     -i : Slave Node id format [0x01 , 0x7F]                *
  *                                                            *
  *    Master:                                                 *
  *     -m : bus name ["1"]                                    *
  *     -M : 1M,500K,250K,125K,100K,50K,20K,10K                *
  *                                                            *
  **************************************************************
\end{verbatim}

\subsection{TestMasterSlaveLSS}


\begin{verbatim}
**************************************************************
*  TestMasterSlaveLSS                                        *
*                                                            *
*  A LSS example for PC. It does implement 3 CanOpen         *
*  nodes in the same process. A master and 2 slaves. All     *
*  communicate together, exchanging periodically NMT, SYNC,  *
*  SDO and PDO. Master configure heartbeat producer time     *
*  at 1000 ms for the slaves by concise DCF.                 *
*                                                            *
*   Usage:                                                   *
*   ./TestMasterSlaveLSS  [OPTIONS]                          *
*                                                            *
*   OPTIONS:                                                 *
*     -l : Can library ["libcanfestival_can_virtual.so"]     *
*                                                            *
*    SlaveA:                                                 *
*     -a : bus name ["0"]                                    *
*     -A : 1M,500K,250K,125K,100K,50K,20K,10K,none(disable)  *
*                                                            *
*    SlaveB:                                                 *
*     -b : bus name ["1"]                                    *
*     -B : 1M,500K,250K,125K,100K,50K,20K,10K,none(disable)  *
*                                                            *
*    Master:                                                 *
*     -m : bus name ["2"]                                    *
*     -M : 1M,500K,250K,125K,100K,50K,20K,10K,none(disable)  *
*                                                            *
**************************************************************
\end{verbatim}

The function used to request LSS services is \textit{configNetworkNode}. It works similar to \textit{writeNetworkDict} and its model is the following:
\begin{verbatim}
UNS8 configNetworkNode (CO_Data* d, UNS8 command, void *dat1, void* dat2, 
LSSCallback_t Callback)
\end{verbatim}

\subsection{FastScan}
FastScan is a special LSS service that allow the dynamically identification of the slave nodes even if they do not have a valid nodeID. This identification is based on the LSS address, composed by vendor ID, product code, revision number and serial number (refer to the DS305 for more information). The LSS address can be partially known or fully unknown. To represent this fact in Canfestival, we use the structure \textit{lss\_fs\_transfer\_t}. The parameter \textit{FS\_LSS\_ID} is an array of four elements which represents the four elements of the LSS address. The other parameter, \textit{FS\_BitChecked}, is also an array and it represents how many bits of each LSS address element are UNKNOWN. The next example is taken from \textit{TestMasterSlaveLSS}, where only the last two digits (8 bits) of vendor ID and product code are unknown and revision number and serial number are totally unknown. 

\begin{verbatim}
lss_fs_transfer_t lss_fs;
/* The VendorID and ProductCode are partialy known, */
/* except the last two digits (8 bits). */
lss_fs.FS_LSS_ID[0]=Vendor_ID;
lss_fs.FS_BitChecked[0]=8;
lss_fs.FS_LSS_ID[1]=Product_Code;
lss_fs.FS_BitChecked[1]=8;
/* serialNumber and RevisionNumber are unknown, */
/* i.e. the 8 digits (32bits) are unknown. */
lss_fs.FS_BitChecked[2]=32;
lss_fs.FS_BitChecked[3]=32;
res=configNetworkNode(&d,LSS_IDENT_FASTSCAN,&lss_fs,0,CheckLSSAndContinue);
\end{verbatim}

\section{Developing a new node}

Using provided examples as a base for your new node is generally a
good idea. You can also use the provided {*}.od files as a base for
your node object dictionary.

Creating a new \canopen node implies to define the Object Dictionary
of this node. For that, developer has to provide a C file. This C
file contains the definition of all dictionary entries, and some kind
of index table that helps the stack to access some entries directly.


\subsection{Using Dictionary Editor GUI}

The Object Dictionary Editor is a WxPython based GUI that is used
to create the C file needed to create a new \canopen node.


\subsubsection{Installation and usage on Linux}

You first have to download and install Gnosis XML modules. This is
automated by a Makefile rule.

\begin{verbatim}
	cd objdictgen 
	make
\end{verbatim}

Now start the editor.

\begin{verbatim}
	python objdictedit.py [od files...]
\end{verbatim}


\subsubsection{Installation and usage on Windows}

Install Python (at least version 2.4) and wxPython (at least version
2.6.3.2).

Cygwin users can install Gnosis XML utils the same as Linux use. Just
call make.

\begin{verbatim}
	cd objdictgen
	make
\end{verbatim}

Others will have to download and install Gnosis XML by hand :

\begin{verbatim}
	Gnosis Utils:
	http://freshmeat.net/projects/gnosisxml/
	http://www.gnosis.cx/download/
	Get latest version.
\end{verbatim}

Download CanFestival archive and uncompress it. Use windows file explorer
to go into CanFestival3\textbackslash{}objdicgten, and double -click
on objdictedit.py.

\subsubsection{About}

The Object Dictionary editor GUI is a python application that use
the Model-View-Controller design pattern. It depends on WxPython to
display view on any supported platform.

\begin{center}
\includegraphics[width=7cm]{Pictures/10000201000001FC000001E5D65E8766} 
\par\end{center}


\subsubsection{Main view}

Top list let you choose dictionary section, bottom left list is the
selected index in that dictionary, and bottom right list are edited
sub -indexes.

\begin{center}
\includegraphics[width=12cm]{Pictures/10000201000003E7000001C7B0296577} 
\par\end{center}

\begin{center}
\includegraphics[width=3cm]{Pictures/10000000000000B6000000DF1EDD1E73} 
\par\end{center}

\begin{center}
\includegraphics[width=3cm]{Pictures/10000000000000AC000000C9C3F53FA6} 
\par\end{center}

\begin{center}
\includegraphics[width=3cm]{Pictures/100000000000006D000000A31EC8CB54} 
\par\end{center}

\begin{center}
\includegraphics[width=3cm]{Pictures/10000000000000AA0000006014F74635} 
\par\end{center}


\subsubsection{New node}

Edit your node name and type. Choose your inherited specific profile.

\begin{center}
\includegraphics[width=11cm]{Pictures/new_node} 
\par\end{center}


\subsubsection{Node info}

Edit your node name and type.

\begin{center}
\includegraphics[width=7cm]{Pictures/node_info} 
\par\end{center}


\subsubsection{Profile editor}