The ftp location is: ftp://metalab.unc.edu/pub/Linux/hardware/drivers/ss5136dn-1.3.tar.gz

Most recent change: Nov. 7, 2001 - Updated links to PCMCIA-HOWTO pages.

Contents

Legal mumbo jumbo

This software is distributed "as is" with absolutely NO WARRANTY WHATSOEVER; without even the implied warranty of merchantability or fitness for a particular purpose.

Neither the author, Laitram Corporation, nor S-S Technologies Inc. provide any official support for this software.

As a further note, the author of this package has taken a position with another company and no longer has access to these SST boards or any DeviceNet nodes! If someone would like to donate me an SST DeviceNet board and some nodes to connect it to, I'd like to continue to develop this driver. Otherwise, the only support I'm able to give is answering basic questions.

The author can be contacted at:

email: marksu@spectra-one.com This document Copyright (c) 1998,1999,2000 The Laitram Corporation.

Introduction, what is this thing?

Can bus is an electrical specification and protocol for communicating with simple intelligent devices over a twisted pair serial network. It has limited capabilities compared to more sophisticated networks (like Ethernet) and has a maximum data rate of 1 megabaud.

Typical uses for CAN bus technology include interfaces to quasi intelligent mechanical devices in industrial automation applications and in automobiles. The "simplified wiring harnesses" in luxury automobiles in which each switch contains a digital chip and the device the switch effects contains another digital chip, and then all the switches and devices are just daisy-chained onto a twisted pair network... that's CAN bus, almost always.

DeviceNet is a protocol that sits on top of CAN bus. DeviceNet is designed primarily for linking quasi intelligent devices to a controlling computer (such as a PC or PLC) in industrial automation applications. In other words, a PC, containing a DeviceNet card, such as the SST models for which this is a driver, would be linked, via a DeviceNet twisted pair, to switches, pneumatic valves, motor starters, step motor controllers, temperature sensors, etc.

By analogy, DeviceNet is to CAN bus as TCP/IP is to Ethernet. CAN is the electrical specification and low level protocol, whereas DeviceNet is the higher Level protocol.

DeviceNet is an open standard. Anyone is welcome to build hardware devices that speak DeviceNet. A non-profit standards organization, the "Open DeviceNet Vendor Association" (ODVA) grants permission for a vendor to declare his product to be DeviceNet compliant based on a test of his product for compliance.

Learn all about DeviceNet by visiting http://www.odva.org

Purpose of this package.

The package contains two drivers, one for the ISA/PC104 flavors of the boards, and another Linux CardServices driver for the PCMCIA version of the board.

These products are CAN bus interface boards containing on board microprocessors and an ability to run on board software modules that define their functionality. They are marketed by SST primarily as DeviceNet interfaces and are typically used running an internal software module called "dnscan.bin" (or "dnscan.ssX") which causes the cards to behave as a DeviceNet "scanner" (a network master) or as a DeviceNet slave device. This software package focuses primarily on using the cards as a DeviceNet scanner (master) device.

Learn all about SST by visiting http://www.sstech.on.ca

Linux Platform Compatibility.

The driver contains a configuration script that configures it for the kernel version being used. It should run on any Linux 2.0.X kernel or 2.2.X kernel running on intel based hardware.

It should run on 2.1.X and 2.3.X series kernels also, but I have not tested it on any of these development kernels.

It has been successfully tested on literally every kernel from 2.0.0 through 2.0.36, and almost every kernel from 2.2.0 through 2.2.14.

SST Product Compatibility.

This package contains a separate driver for the PCMCIA version of the board, the 5136-DN-PCM.

Several other companies sell rebranded versions of these SST products. This package should work with those products also. For example, the Omron DeviceNet interface boards have been reported to work. We have personally tested the Omron 3G8E2-DRM21 PCMCIA DeviceNet interface with the PCMCIA driver and found it to work.

SST also makes a VME version. VME bus is an entirely different animal to ISA and it's cousins (like PC104 and PCMCIA), so this driver has no relevance to the VME version.

Other Required Reading and Resources.

The "Can 2.0 A Module" and "Can 2.0 B Module" reference manuals are also recommended reading. They also come on the CD-Rom that came with your board, and are available at the above web site.

For the board to wake up and do anything, you need to load into it and start an application module. You need to run either "dnscan.bin", "can2a.bin", or "can2b.bin". These are also available on the CD-Rom, or you can download them from the above web site. Get them from the web site to guarantee you have the very latest version.

The latest version of the package will now decrypt and load the encrypted versions of the application modules. They are named the same as above but have the extension "ss1" for the classic board and "ss2" for the pro board. When using the encrypted modules, the package prevents loading the wrong module into the wrong type board (classic vs. pro). (It goes by the extension.)

The executable utility programs, devqry, devset, and devwho, autodetect the board type and load the correct module automatically. The correct module must be present in the working directory.

SST's copyright requirements forbid the inclusion of the above documentation and modules with this package. However, they are trivial to get (if you have the board you have them anyway), so that's no big deal.

Important note if you are upgrading.

This device had been assigned major number 144 by the Linux kernel maintainers. SUSE inadvertently usurped the major number 144 for an encapsulated PPP driver that they had developed. Before this error was caught, there were more users of the encapsulated PPP driver than this driver.

So... It would put less people out to change the major number of this device than the encapsulated PPP. The new major number for this device is 183.

So, If you are upgrading, you have two options:

Option 1 (probably the better option):

Before running the new driver, delete /dev/ss5136dn0. then recreate it with the command: "mknod /dev/ss5136dn0 c 183 0"

Option 2 (probably not the better option, as it may cause a future conflict):

Before compiling the new driver, if you are compiling the ISA/PC104 version, edit k_compat.h to change the line:

#define SS5136DN_MAJOR 183

#define SS5136DN_MAJOR 144

Installing the ISA/PC104 driver.

For the PCMCIA card (5136-DN-PCM) refer to the next section.

• Unpack the distribution tar file somewhere convenient.
• cd to "dn5136drv".
• edit ss5136dn.h to match your card's hardware configuration (see below).
• If you are re-compiling this driver because you have upgraded your kernel, type "make clean". This will cause the makefile to re-check the kernel version and create a new kernelversioninfo.h, among other important things.
• Type "make".
• Type "make install." (Not necessary if you will load the module manually, see below.)
• Create a device file as follows:
  • As root, cd to /dev.
  • If you are running a kernel earlier than 2.2.0, type "mknod ss5136dn0 c 120 0"
  • If you are running kernel 2.2.0 or later, type "mknod ss5136dn0 c 183 0".
  • Type "ln -s ss5136dn0 ss5136dn". (This is for backward compatibility with older programs. If you have never installed an earlier version than this one, and never used earlier versions of the utilities, this is probably not necessary.)
  • If you are running a kernel earlier than 2.2.0, and you already have a device with major number "120", use another number and edit k_compat.h accordingly before making the driver. The official major number for this device is 183, but the 2.0.X series of kernels only allows major numbers up to 128. So for those kernels, we use an "experimental" major number.

Here are a few things you may need to edit in "ss5136dn.h" for your specific installation:

• "#define SS5136DN_WINDOW32K". The official word now is "Don't fool with this". 32K window's are unreliable with this driver for some reason, 16K windows are fine. The driver comes configured for 16K. Leave it that way.
• "#define SS5136DN_PORTBASE 0x250" Make sure this matches the value set via dip-switches on your card. Make sure it doesn't conflict with other cards.
• "define SS5136DN_MEMBASE 0xd000" Use this to define where in memory you want the card to map in. 0xd000 is the most common default. The driver will softset the card to the value specified here when the driver is inserted via insmod or by kerneld. Make sure this value doesn't conflict with a memory block used by another device.

Installing the PCMCIA driver.

The PCMCIA version of the driver is written according to the standards defined in David Hinds' CardServices for Linux package. It is designed to be installed as a contributed driver on top of that package.

To use it, you must have loadable module support enabled in your kernel, and you must have David Hinds' CardServices (PCMCIA) package, and its source tree, installed on your machine.

If you have a laptop running Linux, and your PCMCIA cards work, you have the above packages, by definition (with the possible exception of the PCMCIA source files, get them from your Linux distribution.)

Before you begin. At least skim the Linux PCMCIA HOWTO document. Particularly the section on Compilation and installation.

Steps to install the driver:

• Create a device file as follows:
  • As root, cd to /dev.
  • If you are running a 2.0.X or 2.1.X series kernel, type "mknod ss5136dn0 c 120 0"
  • If you are running a 2.2.X series kernel, type "mknod ss5136dn0 c 183 0" (Note that "183" is the officially assigned major number for this device, but the 2.0 series kernels do not allow a major number greater than 128, so on those kernels, we use an "experimental" major number.)
  • If you are using a 2.0.X or 2.1.X series kernel, and you already have a device with major number "120", use another number and edit ss5136dn_cs.h accordingly before re-making the PCMCIA package. You will find this file in the "modules" directory after you unpack the PCMCIA driver package.
  • While still in directory "/dev" type:
    "ln -s ss5136dn0 ss5136dn".
• There are a few other constants in the ss5136_cs.h file that you might want to edit. See below.
• Connect to the root directory of the PCMCIA source tree. On recent RedHat distributions, this directory is "/usr/src/linux/pcmica-cs-<version>". On older RedHat distributions, and some other popular distributions, it will be in "/usr/src/pcmica-cs-<version>". Consult the docs for your distribution if you have trouble finding it.
• Unpack the file "ss5136dn_cs-<version>.tar.gz" on top of the PCMCIA source tree. This file can be found in the directory "pcmcia" under the ss5136dn driver distribution.
• Type "make config". Answer the questions it asks. Refer to The Linux PCMCIA HOWTO document for assistance. In most cases, you can just accept all of the defaults.
• Type "make all" then "make install".
• Edit the file "/etc/pcmcia/config" as follows:
  In the "device driver definitions" section, add the following block:

  device "ss5136dn_cs"
    module "ss5136dn_cs"
  

  In the "miscellaneous card definitions" section add:

  card "SST 5136-DN-PCM Devicenet Interface"
    manfid 0x01a1, 0x0010
    bind "ss5136dn_cs"
  

• Type "cardctl eject" and remove all your PCMCIA cards. (Optional, but recommended.)
• Type "killall -HUP cardmgr".
• Reinsert your PCMCIA cards one by one, include the 5136 card.
• If the install was successful, when you insert the 5136 card, your computer should make a high pitched beep and the top LED on the card's external box should briefly flash red and then turn green.

• "#define SS5136DN_MAJOR 120". You may change the major number if you are using a 2.0.X series kernel, and 120 is already in use on your system. If you are using a 2.2.X or 2.3.X series kernel, you should almost always use the offical number, 183. Make sure the number you give in the "mknod" command and the value in "ss5136dn_cs.h" match.
• "#define SS5136DN_PORTBASE 0x250" This defines the port address to use.
• "define SS5136DN_MEMBASE 0xd000" Use this to define where in memory you want the card to map in. Make sure this value doesn't conflict with a memory block used by another device.

Using the utility program "devwho".

Type "make devwho".

Before executing the "devwho" program you just compiled, make sure that you have the correct devicenet scanner module (taken from the CDROM that came with the card, or downloaded from SST's web site) located in the connected directory. If you are using a 5136-DNP (ISA or 104) card, you should have "dnscan.ss2" available, if you are using a 5136-DN (ISA, 104, or PCMCIA) card, you should have "dnscan.ss1" available.

Execute "devwho".

The program will prompt you for the following:

• The macid to use for the scanner.
• The baud rate to use for the scanner.
• The lowest macid to probe for on the network.
• The highest macid to probe for on the network.

The program will then begin to chug away, probing by brute force to find devices who's macids are in the range you specified.

Hint: When entering the lower and upper macids to check, bracket the id's that you believe to really exist on the network fairly closely. When the program probes a macid where there really is a device, it almost always finds it quite quickly. However, when it probes a macid where their is no device, it waits for a fairly lengthy timeout. So... If you have only 3 or 4 devices on a network and you give it a range of 0 to 63, you are going to have quite a wait before it finishes.

After it has found all the devices, it will ask you if you want to bring all the devices on line and begin scanning the network. Answer y or n. Answering "n" will just exit, and is useful if you simply wanted to identify all the active macids on the network.

If you answer "y", all the devices will come on line and you will be given a simple command line menu that will allow you to read and write to the active devices. The selections are fairly self explanatory.

The things that will make this utility bomb are the same sorts of things that will make the DeviceNet network itself bomb. These include:

• Incorrectly terminated network trunk.
• The baud rate of all devices on the network not matching.
• Duplicated macids on the network.

Using the utility program "devqry".

Type "make devqry".

Before executing the "devqry" program you just compiled, make sure that you have the correct devicenet scanner module (taken from the CDROM that came with the card, or downloaded from SST's web site) located in the connected directory. If you are using a 5136-DNP (ISA or 104) card, you should have "dnscan.ss2" available, if you are using a 5136-DN (ISA, 104, or PCMCIA) card, you should have "dnscan.ss1" available.

Execute "devqry".

The program will prompt you for the following:

• The macid to use for the scanner.
• The baud rate to use for the scanner.
• The macid of the device to query.

The program will return the number of probed and strobed inputs and outputs that the device reported that it had. It will also report a few other device-reported parameters such as vendor-id and product code.

Using the utility program "devset".

Type "make devset".

Before executing the "devset" program you just compiled, make sure that you have the correct devicenet scanner module (taken from the CDROM that came with the card, or downloaded from SST's web site) located in the connected directory. If you are using a 5136-DNP (ISA or 104) card, you should have "dnscan.ss2" available, if you are using a 5136-DN (ISA, 104, or PCMCIA) card, you should have "dnscan.ss1" available.

Execute "devset".

The program will prompt you for the following:

• The macid to use for the scanner.
• The baud rate to use for the scanner.
• The macid of the device to set.
• Whether to set the baud rate or macid of the device or whether you want to turn open circuit detection on or off. (Not all devices support open circuit detection. If you select this option on a device that doesn't support it, an error will simply be produced).
• The new value for the baud rate, macid, or selection for open circuit detection.

The recommended procedure for using this utility on such a device would be:

• Start the program with a scanner macid of 0 and baud rate of 125.
• Select macid 63 as the macid to set.
• Select baud rate as the parameter to set.
• Select the new baud rate for the device.
• The program will report success or failure and exit.
• Assuming the program reported success, power cycle the device to cause the change to take effect.
• Use the "devqry" utility to confirm that the device is now operating at the new baud rate.
• Repeat the above steps except use the new baud rate you previously set for the device and select "macid" as the parameter to change.
• Use "devqry" again to confirm that the macid successfully changed.

Writing your own code to talk to the driver.

Note that the "dnuser" user library provides higher level functionality then these low level driver calls. You'll need to know about these only if you are adding functionality to the user library.

The driver provides the following standard character device functions:

• read
• write
• ioctl
• open
• close

The following ioctls are provided:

• SS5136DN_SETCARDMEMPTR: Sets the pointer to card memory. Use this as you would "seek" on a block device to position your read/write pointer prior to a read or write. Takes one integer argument, the offset from memory base to the pointer.
• SS5136DN_BIGRESET: Resets the card. Takes no argument. This is a hard reset. The card memory is cleared and the on-board processor is hard rebooted.
• SS5136DN_SHUTDOWN: Shuts down the card. Takes no argument.
• SS5136DN_REPORT_APERATURE: Returns the size of the memory aperture that the card is configured for. The value will be 0x4000 (16k) or 0x8000 (32k).
• SS5136DN_REPORT_CARDTYPE: Returns the type card installed; "PRO" or "REGULAR".
• SS5136DN_WRITEREG: Generic write to a i/o port. Takes an argument that is a pointer to type "portiopair". (See the .h files).
• SS5136DN_READREG: Generic read of an i/o register. Takes a pointer to type "portiopair".
• SS5136DN_PAGECHANGE: Changes the memory page on the card. Takes an integer argument "pagenum".
• SS5136DN_MEMENABLE: Enables the card memory. Takes no argument.
• SS5136DN_MEMDISABLE: Disables the card memory. Takes no argument.
• SS5136DN_PROCENABLE: Enables the card's on board processor. Takes no argument.
• SS5136DN_PROCDISABLE: Disables the card's on board processor. Takes no argument.
• SS5136DN_WDENABLE: Enables the watch dog timer. Takes no argument.
• SS5136DN_WDDISABLE: Disables the watch dog timer. Takes no argument.
• SS5136DN_HLTHGREEN: Turns the "health LED" green. Takes no argument.
• SS5136DN_HLTHRED: Turns the "health LED" red. Takes no argument.
• SS5136DN_CLINT: Clears the card's PC (output) interrupt latch. Takes no argument.
• SS5136DN_STROBECINT: Strobes the interrupt line of the card's on-board microprocessor to make it process a command. Takes no argument. Do not confuse this with the PC interrupt latch accessed via "SS5136DN_CLINT".

User Library functions

The library contains the following functions: