16525 East Laser Drive
Fountain Hills, AZ 85268
Phone (480) 837-5200
Technologic Systems' Logo

Table of Contents

1 Introduction

2 Getting Started

3 TS-SOCKET Features

4 TS-SOCKET Software Guide

5 TS-SOCKET Common Pinouts

Appendix A: Further References

Appendix B: Revision History


1 Introduction

1.1 About this Manual

This manual is intended to provide the user with a generic overview of TS-SOCKET Macrocontrollers, its benefits, setup and usage procedures, and feature specifications which are generic to all TS-SOCKET Macrocontroller series. This manual serves as the main complement to any of the TS-4XXX Manuals. For specific information regarding your product, please refer to its manual which can be found in Appendix A: Further Resources.

1.2 Feedback and Update to this Manual

To help our customers make the most of our products, we are continually making additional and updated resources available on the Technologic Systems website at http://www.embeddedarm.com.

These include manuals, application notes, programming examples, and updated software and firmware. Check in periodically to see what's new!

When we are prioritizing work on these updated resources, feedback from customers (and prospective customers) is the number one influence. If you have questions, comments, or concerns about your Embedded Computer, please let us know at support@embeddedarm.com.

1.3 Limited Warranty

Technologic Systems warrants this product to be free of defects in material and workmanship for a period of one year from date of purchase. During this warranty period Technologic Systems will repair or replace the defective unit in accordance with the following process:

A copy of the original invoice must be included when returning the defective unit to Technologic Systems, Inc. This limited warranty does not cover damages resulting from lightning or other power surges, misuse, abuse, abnormal conditions of operation, or attempts to alter or modify the function of the product.

This warranty is limited to the repair or replacement of the defective unit. In no event shall Technologic Systems be liable or responsible for any loss or damages, including but not limited to any lost profits, incidental or consequential damages, loss of business, or anticipatory profits arising from the use or inability to use this product.

Repairs made after the expiration of the warranty period are subject to a repair charge and the cost of return shipping. Please, contact Technologic Systems to arrange for any repair service and to obtain repair charge information.

1.4 FCC Advisory Statement

This equipment generates, uses, and can radiate radio frequency energy and if not installed and used properly (that is, in strict accordance with the manufacturer's instructions), may cause interference to radio and television reception. It has been type tested and found to comply with the limits for a Class A computing device in accordance with the specifications in Subpart J of Part 15 of FCC Rules, which are designed to provide reasonable protection against such interference when operated in a commercial environment. Operation of this equipment in a residential area is likely to cause interference, in which case the owner will be required to correct the interference at his own expense.

If this equipment does cause interference, which can be determined by turning the unit on and off, the user is encouraged to try the following measures to correct the interference:

  • Reorient the receiving antenna.
  • Relocate the unit with respect to the receiver.
  • Plug the unit into a different outlet so that the unit and receiver are on different branch circuits.
  • Ensure that mounting screws and connector attachment screws are tightly secured.
  • Ensure that good quality, shielded, and grounded cables are used for all data communications.
  • If necessary, the user should consult the dealer or an experienced radio/television technician for additional suggestions.

The following booklets prepared by the Federal Communications Commission (FCC) may also prove helpful:

  • How to Identify and Resolve Radio-TV Interference Problems (Stock No. 004-000-000345-4)
  • Interface Handbook (Stock No. 004-000-004505-7)

These booklets may be purchased from the Superintendent of Documents, U.S. Government Printing Office, Washington, DC 20402.

1.5 Software and Support

Technologic Systems provides:

  • Free system software and documentation updates available on our web site
  • Free technical support by phone, fax, or email
  • 30-day, money back guarantee on evaluation units
  • One-year, full warranty
  • Linux OS Support

1.6 Conventions Used

Filenames and code statements are presented in Courier.

   Similarly, code blocks or sections better suited for
   plain text display, such as example terminal output, 
   are presented in indented preformatted text.

Commands issued by the reader are indicated in bold Courier. New terms or important concepts are presented in italics.

When you see a pathname preceded with three dots, this references a well-known but unspecified top-level directory. The top-level directory is context dependent but almost universally refers to a top-level Linux source directory. For example, .../arch/arm/kernel/setup.c refers to the setup.c file located in the architecture branch of a Linux source tree. The actual path might be something like ~/sandbox/linux.2.6.21/arch/arm/kernel/setup.c.

Hardware interfaces, such as pin numbers or names, are described by ALL CAPS.

NOTE:

Text appearing in this manner offers notes and/or comments that will aid in your understanding.

WARNING:

Text appearing in this manner offers a warning. You can make a mistake here that hurts your system or is hard to recover from.

1.7 TS-SOCKET Series

The TS-SOCKET standard is an embedded computer standard designed and controlled by Technologic Systems, Inc. It defines both a form factor and a connection pin-out and is based on two 100-pin low-profile connectors, allowing secure connection between a TS-SOCKET Macrocontroller (CPU board) and a baseboard. Please refer to the TS-SOCKET Standard and Embedded Macrocontrollers resource for more information.

1.8 TS-ARM Development Kit

The TS-ARM Development Kit for the TS-SOCKET series includes all equipment necessary to boot into the operating system of choice and start working. The development kit is highly recommended for a quick start on application development. For example, the TS-ARM Development Kit for the TS-4200 (KIT-4200) includes:

  • Development 2GB microSD with ECLIPSE IDE and USB microSD card reader (MSD-2GB-USB-4200)
    • Debian Linux 5.0 (Lenny) Distribution compiled for ARM
    • Full tool-chains (uclibc and glibc) for cross compiling for ARM
    • Utility source code (ie. sdctl.c) and example programs
  • TS-8200 development platform including low cost plastic enclosure (TS-ENC820)
  • Regulated DC power supply and all cables including NULL Modem cable, etc.

NOTE:

Single board computer is not included in the Development Kit (sold separately).

1.10 Benefits

Out-of-the-Box Productivity

Technologic Systems Linux products get you to your application quickly. Our Single Board Computers boot directly to Linux as shipped. There is no complicated CMOS setup or configuring of a Linux derivative Operating System to source, define, and load. A Technologic Systems SBC user can power up the board and immediately begin application development.

Of course, should you wish to configure your own version of Linux or use a different operating system, this is easy too. Technologic Systems provides the solution to fast application development without tedious OS configuration.

Small Form Factor

The TS-4200 is nearly the same size as a credit card which gives it an advantage when being considered for an application with very tight space limitations or constrictions. Mating high density connectors (available from the TS-4200 website) make it easy for you to design a baseboard or connection system that brings out only the features of the TS-4200 that you need which can further help you squeeze the TS-4200 into your application.

Future Ready

Modularity is the focus with the TS-SOCKET standard. Baseboards designed for one TS-SOCKET Macrocontroller will have high, drop-in compatibility with future release of another TS-SOCKET Macrocontroller. With this, you don't need to be concerned about being locked into one particular design, giving your application leg room to grow.

A Plethora of External Connections

The TS-SOCKET Macrocontrollers offer many connections and buses via the high density connectors, such as GPIO, SPI, I2C, I2S, that give the TS-SOCKET Macrocontrollers the added benefit of being able to interact with external peripherals and sensors.

Talk with Engineers Directly

At Technologic Systems, our Embedded Systems Engineers answer to both support requests as well as sales inquiries. If you have any questions about the TS-SOCKET standard, Linux kernel or distribution, baseboard layout, or just questions, they are here to help.

2 Getting Started

2.1 Installation Procedure

Before performing any set up or placement procedures, take the precautions outlined in this section.

Handling the Board Safely

The TS-SOCKET Macrocontrollers use two high density 100 Pin connectors which are rated for about 100 insertions. Take care to not wear out this connector. If you are to be inserting and removing the modules from the baseboards, you may want to consider placing a wear-out board with mating connectors in between the baseboard and the modules so it can easily thrown out and replaced with a new one.

WARNING:

The TS-SOCKET Connectors are limited to number of insertions.

Be sure to take appropriate Electrostatic Discharge (ESD) precautions. Disconnect the power source before moving, cabling, or performing any set up procedures.

WARNING:

Inappropriate handling may cause damage to the board.

Setup and Installation Instructions

Follow these guidelines for safety and maximum product performance:

  • Observe local health and safety requirements and guidelines for manual material handling

Setup Tools

Depending on placement and cabling, you may need the following tools:

  • Small flat-blade screwdriver
  • Small Phillips screwdriver

Setup Procedure

After locating, setting up, grounding, and cabling the TS-SOCKET SBC:

  • Apply power
  • Monitor the TS-SOCKET SBC using a terminal emulator to verify that the board is operating properly

NOTE:

Your TS-SOCKET Baseboard might include a screw power connector on the power input. Notice this connector is removable. Please pull this connector off before applying power.

Disconnecting AC Power

  • Unplug from the power source.
  • Disconnect other cables as required.

2.2 Console and Power Up

An ANSI terminal or a PC running a terminal emulator is required to communicate with your TS-SOCKET single board computer. Simply connect an ANSI terminal (or emulator) to the COM DB-9 header using a null modem cable (these are included in the TS-ARM Development Kit), using serial parameters of 115,200 baud, 8 data bits, no parity, no flow control, 1 stop bit (8N1). If you are running Linux, the minicom program works well, Windows XP users can run the Hyperterm application, and Windows Vista (or later) users can download and run PuTTy. A more detailed explanation is available in "4.1 Connecting via Serial Console".

Depending on your TS-SOCKET Baseboard, connect a regulated power source on the power input connector (ie. TS-8200 requires 5 - 12VDC, minimum 1A). Please note the polarity printed on the board. The boot messages, by default, are all displayed on the DB9 COM port at 115200 baud. The board will also answer telnet connections to IP address 192.168.0.50.

Most TS-SOCKET Macrocontrollers are equipped with Linux on onboard flash. Upon bootup, The board will boot within 3 seconds to a Linux prompt typically found on UART #0 (/dev/ttyS0).

The default fastboot shell has available several standard Linux commands through the busybox program. Technologic Systems has made several modifications to the busybox source code to keep bootup as fast and simple as possible. The modified source code is available to Technologic Systems customers.

Upon bootup, you should see out of your serial port when booting from a properly formatted SD card something similar to:

   >> TS-BOOTROM - built Jan  4 2010 15:26:01
   >> Copyright (c) 2009, Technologic Systems
   >> Booting from onboard NAND flash...
   .
   .
   .
   .
   Finished booting in 3.10 seconds
   Type 'tshelp' for help
   /#

At this point, if you type 'exit' from the serial shell, the TS-SOCKET Macrocontroller will then attempt a full Debian Linux bootup from the onboard XNAND flash using partition #3 as the root file system, or from an inserted SD card using partition #4 as the root file system if the SD card is present. The version of Linux located on the SD card is an embedded version of Debian Linux and contains Apache, SSH, PPP, and FTP server and many other common utilities and libraries. The version of Linux located on the XNAND flash is the same as the SD card, but with the larger packages removed so it can be squeezed into the 256MB XNAND Drive. Other community-supported embedded Linux distributions are available. For instance, the "Buildroot" project at http://buildroot.uclibc.org/ allows one to easily build custom filesystems and cross-toolchains.

Should the need arise to automatically bypass the fastboot shell and proceed directly to a different starting point such as SD, NFS, or USB, you can do so by linking the appropriate linuxrc-* file to linuxrc. For example, to boot directly to the microSD card, use the following command:

   ln -sf /linuxrc-sdroot /linuxrc; save

To get back to the fastboot shell at the next boot up, place the file /fastboot in the root directory of the filesystem using touch /fastboot.

The '/linuxrc' file is a shell script that is the very first thing run by the kernel on startup. Several sample startup scripts are included and can either be used directly ("ln -sf /linuxrc-XXX /linuxrc" command) or modified to include custom bootup logic. These shell scripts were designed to be as fast and simple as possible for easy customer modifications. It is anticipated that this shell script be modified from the default to implement things in the customer's product such as backup configurations, software field updates, conditional booting/verification of SD cards, etc. Technologic Systems professional services are available should you need help in implementing a specific feature.

2.3 Recovery

If you botch a modification during development with the TS-SOCKET Macrocontrollers, it is easy to recover it to a previous factory state using the provided shell subroutines located in /ts4000.subr. For example, to restore the TS-4200 XNAND Flash to factory state, boot to a working microSD card and issue the command sd2nand. Another command called recover is smart enough to know where you have booted from and what needs to be recovered. Type tshelp for a list of commands supported.

Alternatively, you may also restore the SD card to the state in which you received it. First, an SD card that has been properly formatted for your TS-SOCKET SBC must be created. The latest images can be downloaded from ftp://ftp.embeddedarm.com/ts-socket-macrocontrollers/. Once the image has been downloaded, it can be copied to the SD card with the following command (assuming /dev/sdb is the device where the SD card is located).

   bzcat ts-sdimage.dd.bz2 | dd of=/dev/sdb

OR

   bunzip2 ts-sdimage.dd.bz2
   dd if=ts-sdimage.dd of=/dev/sdb

2.4 Busybox Environment

After booting in about 3.10 seconds, the TS-SOCKET Macrocontroller presents a Linux shell on the serial console. Standard Linux utilities are provided by the busybox program. Type help for a list of provided utilities. Source code for the busybox utility is available on the Technologic Systems FTP site.

A shell subroutine file, ts4000.subr, will be in the root directory. This file is executed at startup and defines several convenient functions. Type tshelp for a list of these features. This can be used from within the Debian environment as well by exporting it with the command . /initrd/ts7000.subr. For example, here is the output after running tshelp on a TS-4500:

   usbload - Load USB kernel drivers
   setdiopin  <1,0,Z> - set DIO header pin 1-44
   getdiopin  - get DIO input state
   setrelay  - turn on/off TS-752 relays according to 3-bit val
   setout  - set 3-bit TS-752 output val
   getin - return 8 bit TS-752 inputs
   gettemp - return Temp. Sensor reading
   save - save initrd back to boot device (NAND, SD or SPI flash)
   sd2nand/nand2sd, sd2flash/flash2sd, nand2flash/flash2nand, etc. -
   (copy initrd image from one media to another)
   recover - recover kernel+initrd images
   sbcTest - run TS production tests
   exit - boot SD card (if present) or filesystem mounted at /mnt/root

In addition, there are several utility programs such as ts4500ctl, sdctl, nandctl, etc. Please refer to 3.1 TS Utilities .

2.5 Loading or Transferring Files

Four methods are available for transferring files between a desktop PC and your TS-SOCKET Macrocontroller: Ethernet downloads, flash memory devices, Zmodem downloads, and NFS server. Full descriptions of each are detailed below. Other programs that use serial ports to transfer should work as well.

Transferring Files via the Ethernet Port

The default Linux root file system includes a small FTP server that can be used for uploading/downloading of files across an Ethernet network. Simply point your preferred FTP client to your TS-SOCKET Macrocontroller IP address (default is 192.168.0.50). You can login as root or any valid user previously created from the useradd utility. By default, the TS-SOCKET Macrocontrollers will not accept anonymous FTP. With the microSD card, a user named "eclipse" is present with password "eclipse".

Transferring Files via Flash Memory Device

A USB thumb drive can be used to easily move files from a host system. USB memory devices need no extra accessory to connect to the host PC. The flash memory devices can then be hot swapped (inserted or removed without rebooting the host PC). As an example, mounting a USB drive on the TS-4500 in the Debian environment can be done using the command:

   mkdir
   /mnt/usbdrive && mount /dev/sda1 /mnt/usbdrive

Mounting a USB drive on the TS-4500 in the Busybox environment can be done by first inserting the USB drive, applying power, and then using:

   mkdir /mnt/usbdrive
   mount /dev/sda1 /mnt/usbdrive

In the case of the TS-4500 linuxrc file, it automatically detects a USB device and then inserts the necessary modules. Should you need to manually configure the USB thumb drive, the following modules are required to be inserted and then follow up with the mdev -s command:

   scsi_mod
   sd_mod
   ohci_hcd
   usb_storage
   usbserial

Zmodem Downloads

Using the Zmodem protocol (not installed by default) to send files to and from the TS-SOCKET Macrocontroller is simple and straightforward. The only requirement is a terminal emulation program that supports Zmodem, and virtually all do. If you are using Windows 95 or later for your development work, the HyperTerminal accessory works well.

To download a file to the TS-SOCKET Macrocontroller from your host PC, execute lrz at the Linux command line (while using console-redirection from within your terminal emulator) and begin the transfer with your terminal emulator. In HyperTerminal, this is 'Send File...' from the 'Transfer' menu.

To upload a file from the TS-SOCKET Macrocontroller to your host PC, execute lsz [FILENAME] at the Linux command line and start the transfer in your terminal emulator. Many emulators, HyperTerminal among them, will automatically begin the transfer themselves.

Occasionally there may be errors in transmission due to background operations. This is not a problem -- Zmodem uses very accurate CRC checks to detect errors and simply resends bad data. Once the file transfer is complete the file is completely error free. For best results when using HyperTerminal, the hardware handshaking must be enabled in HyperTerminal.

NFS Server

Although this method can be a bit more involved, it's the fastest, easiest, and preferred way to transfer files to and from a development PC. Basically, setup a development PC running Linux and set it up as an NFS server to share a directory (see online documentation for accomplishing this such as this one on sourceforge). Mount the NFS server on a folder on the SBC and transfer files to and from that folder. You can even work directly in the folder. The command to mount an NFS server would look similar to this:

   mkdir /mnt/nfsshare && mount -t nfs -o nolock,vers=2 192.168.1.100:/share /mnt/nfsshare

2.6 XNAND Drive and microSD Partition Layout

The XNAND Drive and microSD card have a special partition scheme to facilitate usage on the TS-SOCKET Macrocontrollers. The XNAND Drive has three partitions whereas the microSD card has an additional partition for the Eclipse IDE making four in total.

XNAND Drive

   /dev/nbd0 -- Entire block device
   /dev/nbd2 -- First MBR partition containing bootloader kernel binary (0xda)
   /dev/nbd3 -- Second MBR partition containing bootloader initrd (EXT2)
   /dev/ndb4 -- Third MBR partition containing Debian root filesystem (ReiserFS)

microSD Card

   /dev/nbd0 -- Entire block device
   /dev/nbd1 -- First MBR partition containing Eclipse IDE (FAT32)
   /dev/nbd2 -- Second MBR partition containing bootloader kernel binary (0xda)
   /dev/nbd3 -- Third MBR partition containing bootloader initrd (EXT2)
   /dev/ndb4 -- Fourth MBR partition containing Debian root filesystem (EXT3)
NOTE:

Note that the MBR installed by default on the TS-SOCKET SBC contains a 446 byte bootloader program that loads the initial power-on kernel and initrd from the first and second partitions. Replacing it with a MBR found on a PC would not work as a PC MBR contains an x86 code bootup program.

2.7 Debian Linux

The typical way of doing Linux development on the TS-SOCKET Macrocontroller is actually on the board itself (see 4.5 Developing on Board). Since the CPU is a PC-class processor in everything but power consumption and performance, it has no problem running real PC-class operating systems such as Linux. By running the full version of Linux (and not scaled-down microcontroller project OS's such as ucLinux), the TS-SOCKET Macrocontroller can run the entire suite of applications contained in the Debian Linux distribution including the compilers. Since almost every open source program available for Linux is contained within the Debian Linux binary distribution, one rarely has to compile the large code-bases that would otherwise have forced integrator to a complicated cross-compilation environment due to the limited RAM/MHz of the embedded computer. All too often, open-source projects do not anticipate the possibility of cross-compilation in their build systems, leaving issues for the system integrator to resolve.

The default microSD card contains compilers and everything needed for developing applications in C, C++, PERL, PHP, and SH. Java, BASIC, TCL, Python and others are available for Debian, but not installed by default.

One can still use cross-compilers hosted on just about any platform if there is a specific need. Technologic systems includes binary versions of the popular Linux "crosstool" project at http://www.kegel.com/crosstool/ or http://www.codesourcery.com to allow cross-compiling on Windows/cygwin or a Linux/i386 PC on our FTP server.

See "4 TS-SOCKET Software Guide" for more software usage examples.

3 TS-SOCKET Features

This chapter contains information regarding features that can be found on the TS-SOCKET products. Some features are not available on all TS-SOCKET Macrocontrollers (ie CAN is not support on TS-4200). Be sure to check with your specific product manual to verify.

3.1 TS "ctl" Utilities

The TS-SOCKET Macrocontrollers are preloaded with many utilities that allow customers to start immediately begin using hardware features such as sdctl, nandctl, dmxctl, canctl, spictl, etc. This section will review each of these utilities. Keep in mind that some features are not available on all TS-SOCKET Macrocontrollers (ie CAN is not support on TS-4200). Be sure to check with your specific product manual to verify.

Utility: ts7500.subr

   
   ts7500:~# tshelp
   usbload - Load USB kernel drivers
   setdiopin <pin> <1,0,Z> - set DIO header pin 1-44
   getdiopin <pin> - get DIO input state
   setrelay <val> - turn on/off TS-752 relays according to 3-bit val
   setout <val> - set 3-bit TS-752 output val
   getin - return 8 bit TS-752 inputs
   gettemp - return TS-752 temperature sensor in Celsius
   save - save initrd back to boot device
   nandsave, sdsave, spiflashsave, spiflash1save - 
   -----save initrd to a media (NAND, mSD or SPI flash)
   sd2nand, nand2spiflash, spiflash2sd, etc - 
   -----copy initrd from one media to another
   sbcTest - run TS production tests
   exit - boot mSD card (if present) or filesystem mounted at /mnt/root

Utility: ts7500ctl

   ts7500:~# ts7500ctl --help
   Usage: ts7500ctl [OPTION] ...
   Technologic Systems SBUS manipulation.

   General options:
     -a, --address=ADR       SBUS address
     -r, --peek16            16-bit SBUS read
     -w, --poke16=VAL        16-bit SBUS write
     -g, --getmac            Display ethernet MAC address
     -s, --setmac=MAC        Set ethernet MAC address
     -R, --reboot            Reboot the board
     -t, --getrtc            Display RTC time/date
     -S, --setrtc            Set RTC time/date from system time
     -i, --info              Display board FPGA info
     -e, --greenledon        Turn green LED on
     -b, --greenledoff       Turn green LED off
     -c, --redledon          Turn red LED on
     -d, --redledoff         Turn red LED off
     -D, --setdio=LVAL       Set DIO output to LVAL
     -O, --setdiodir=LVAL    Set DIO direction to LVAL (1 - output)
     -G, --getdio            Get DIO input
     -Z, --getdioreg         Get DIO direction and output register values
     -x, --random            Get 16-bit hardware random number
     -W, --watchdog          Daemonize and set up /dev/watchdog
     -A, --autofeed=SETTING  Daemonize and auto feed watchdog
     -n, --setrng            Seed the kernel random number generator
     -X, --resetswitchon     Enable reset switch
     -Y, --resetswitchoff    Disable reset switch
     -I, --extendedtempon    Enable extended temp (200Mhz CPU)
     -C, --extendedtempoff   Disable extended temp (250Mhz CPU)
     -l, --loadfpga=FILE     Load FPGA bitstream from FILE
     -T, --gettemp           Print board temperature
     -h, --help              This help

Utility: sdctl

   ts7500:~# sdctl --help
   Usage: sdctl [OPTION] ...
   Technologic Systems SD core manipulation.

   General options:
     -R, --read=N            Read N blocks of SD to stdout
     -W, --write=N           Write N blocks to SD
     -x, --writeset=BYTE     Write BYTE as value (default 0)
     -i, --writeimg=FILE     Use FILE as file to write to SD
     -t, --writetest         Run write speed test
     -r, --readtest          Run read speed test
     -n, --random=SEED       Do random seeks for tests
     -o, --noparking         Disable write parking optimization
     -z, --blocksize=SZ      Use SZ bytes each sdread/sdwrite call
     -E, --erasehint=SZ      Use SZ bytes as erase hint
     -b, --sdboottoken=TOK   Use TOK as the boot token (to quicken init)
     -a, --address=ADD       Use ADD address instead of 0x13000000
     -k, --seek=SECTOR       Seek to 512b sector number SECTOR
     -l, --lun=N             Use N as numbered card slot (default 0)
     -S, --scanluns          Scan all LUNs for cards
     -m, --nodma             Don't use DMA
     -d, --nbdserver=NBDSPEC Run NBD userspace block driver server
     -I, --bind=IPADDR       Bind NBD server to IPADDR
     -Q, --stats             Print NBD server stats
     -P, --printmbr          Print MBR and partition table
     -M, --setmbr            Write MBR from environment variables
     -f, --foreground        Run NBD server in foreground
     -h, --help              This help

   Security/SD lock options:
     -p, --password=PASS     Use PASS as password
     -c, --clear             Remove password lock
     -s, --set               Set password lock
     -u, --unlock            Unlock temporarily
     -e, --erase             Erase entire device (clears password)
     -w, --wprot             Enable permanent write protect

   When running a NBD server, NBDSPEC is a comma separated list of
   devices and partitions for the NBD servers starting at port 7500.
   e.g. "lun0:part1,lun1:disc" corresponds to 2 NBD servers, one at port
   7500 serving the first partition of SD lun 0, and the other at TCP
   port 7501 serving the whole disc device of SD lun #1.

Utility: nandctl

   ts7500:~# nandctl --help
   Usage: nandctl [OPTION] ...
   Technologic Systems NAND flash manipulation.

   General options:
     -R, --read=N            Read N blocks of flash to stdout
     -W, --write=N           Write N blocks to flash
     -x, --writeset=BYTE     Write BYTE as value (default 0)
     -i, --writeimg=FILE     Use FILE as file to write to NAND
     -t, --writetest         Run write speed test
     -r, --readtest          Run read speed test
     -n, --random=SEED       Do random seeks for tests
     -z, --blocksize=SZ      Use SZ bytes each read/write call
     -k, --seek=SECTOR       Seek to 512b sector number SECTOR
     -e, --erase=NSECTORS    Erase NSECTORS 512b sectors
     -d, --nbdserver=NBDSPEC Run NBD userspace block driver server
     -I, --bind=IPADDR       Bind NBD server to IPADDR
     -Q, --stats             Print NBD server stats
     -f, --foreground        Run NBD server in foreground
     -l, --lun=N             Use chip number N
     -X, --xnand             Use XNAND RAID layer
     -A, --autormw           Use AUTORMW layer
     -s, --stress=BLOCK      Stress block BLOCK until it breaks
     -H, --hwtest=BLOCK      Hardware profile block BLOCK
     -b, --break=SECTOR      Erase sector SECTOR for testing
     -I, --xnandinit=NSECT   Initialize flash chip for XNAND RAID
     -L, --listbb            List all factory bad blocks
     -a, --audit             Check integrity of XNAND data
     -Y, --yes               Answer yes to all audit repairs
     -N, --no                Answer no to all audit repairs
     -v, --verbose           Be verbose (-vv for maximum)
     -P, --printmbr          Print MBR and partition table
     -M, --setmbr            Write MBR from environment variables
     -h, --help              This help

   When running a NBD server, NBDSPEC is a comma separated list of
   devices and partitions for the NBD servers starting at port 7525.
   e.g. "lun0:part1,lun1:disc" corresponds to 2 NBD servers, one at port
   7525 serving the first partition of chip #0, and the other at TCP
   port 7526 serving the whole disc device of chip #1.

Utility: dmxctl

   ts7500:~# dmxctl --help
   Technologic Systems DMX application
   -l | --listen=<seconds>   capture DMX packets and print to stdout
   -r | --replay=<file>      play DMX events as specified in file
   -a | --autosend           sends DMX packets even when no new events occur
   -c | --channels=<num>     send the specified number of DMX channels
   -s | --server=<port>      run as a server.  The default port is 7033.
   -i | --client=<host:>port connect to the specified DMX server
   -i | --client=dev         connect to the specified UART device
   -m | --demo               play a demo sequence
   Need to specify exactly one of --server, --client, or --device.

Utility: canctl

   ts7500:~# canctl --help
   Technologic Systems CAN controller manipulation.
   -a | --address=ADR        CAN register address
   -b | --baud=BAUD          CAN baud rate (7500 to 1000000)
   -R | --peek8r             CAN register read
   -W | --poke8w=VAL         CAN register write
   -i | --txid=ID            CAN TX packet ID
   -T | --txrtr              TX RTR packet
   -d | --txdat=DAT          TX packet with data DAT
   -s | --server==<port>     Daemonize and run as server
   -D | --dump               Receive and print all CAN packets
   -0 | --btr0=BTR0          SJA1000 BTR0 bus timing reg val
   -1 | --btr1=BTR1          SJA1000 BTR1 bus timing reg val
   -t | --txtest             Send TX test pattern
   -r | --rxtest             Do RX test
   -p | --port=<host><:port> Talk to canctl server

Utility: dioctl

   ts7500:~# dioctl --help
   Technologic Systems DIO controller manipulation.

   General options:
   -s | --server=<port>      Daemonize and run as server listening on port
   -p | --port=<host><:port> Talk to dioctl server
   -g | --getcaps            Get DIO capabilities
   -r | --read=DIOnum        Read the state of the specified DIO
   -1 | --1=DIOnum           set the specified DIO to output and drive high
   -0 | --0=DIOnum           set the specified DIO to output and drive low
   -i | --input=DIOnum       set the specified DIO to an input
   -G | --group=num:val1...  set the specified DIO Group number to the list of DIOs
   -w | --wait=num:val1...   wait for any DIO in the specified group number to be the given value
   To specify a DIO group where a DIO number is expected, add 1000 to the group number.

Utility: spictl

   ts7500:~# spictl --help
   Technologic Systems SPI controller manipulation.

   General options:
   -c | --clock=frequency    SPI clock frequency
   -e | --edge=value         set clock edge (positive for > 0, negative for < 0)
   -w | --writestream=data   write colon delimited hex octets to SPI
   -d | --readwrite=data     write colon delimited hex octets to SPI while reading to stdout
   -r | --readstream=bytes   read specified number of bytes from SPI to stdout
   -o | --holdcs             don't de-assert CS# when done
   -l | --lun=id             Talk to specified chip number
   -s | --server=<port>      Daemonize and run as server listening on port
   -p | --port=<host><:port> Talk to spictl server
   hex octets are hexadecimal bytes. for example,
   this command reads 32 bytes of CS#1 SPI flash from address 8192:
   ./spictl -l 1 -w 0B:00:20:00:00 -r 32 <host><:port>

Utility: guictl

A graphical user interface (GUI) control utility that is currently under development.

Utility: twictl

An I2C control utility which is on our continuing list of utilities to create but has not been prioritized.

3.2 Ethernet Connectors

APPLICABLE PRODUCTS: TS-8100, TS-8200, TS-8160

The RJ-45 Ethernet connector (with internal magnetics) installed on the TS-SOCKET Baseboard is connected via CN2 of the TS-SOCKET. The connector has both LINK and ACTIVITY LEDs that indicate the current Ethernet status. The LINK LED (right side of connector, green) is active when a valid Ethernet link is detected. This LED should be ON whenever the TS-SOCKET Baseboard is powered, the eth0 interface is up, and properly connected to an 10/100 Ethernet network. The two speeds supported are 10BASE-T and 100BASE-TX. When the link is established the correct speed is selected using autonegotiation to set the speed and duplex for the best values supported by both connected devices. If auto-negotiation fails, a multiple speed device will sense the speed used by its partner, but will assume half-duplex. The Linux kernel has all the software/driver support necessary to use this Ethernet connector as provided by the CPU manufacture. For more details, refer to the TCP/IP configuration instructions in third-party Linux documentation.

Some TS-SOCKET Baseboards (e.g. TS-8100) offer an optional second RJ-45 Ethernet connector (with internal magnetics). This second Ethernet connector is controlled by a USB to Ethernet chip (smsc9514) and requires the smsc95xx.ko driver to function. This interface will appear in Linux as usb0. This connector, like the first Ethernet connector, has both LINK and ACTIVITY LEDs that indicate the current Ethernet status.

NOTE:

The smsc9514 USB to Ethernet adapter also provides a 4 port USB hub (downstream), of which each USB port may or may not be brought out, depending on the specific TS-SOCKET Baseboard (refer to schematics).

3.3 USB Connectors

APPLICABLE PRODUCTS: TS-8100, TS-8200, TS-8160

The USB connectors installed on the TS-SOCKET Baseboard are connected via CN2 of the TS-SOCKET. These USB connectors provide high-speed USB interfaces for the user (both host and device). Generally, these connectors are directly connected to the TS-SOCKET Macrocontroller CPU via the TS-SOCKET. Depending on the TS-SOCKET Baseboard, these connectors may be connected to a USB hub such as the smsc9514 USB to Ethernet plus 4-Port USB Hub chip (refer to schematics). Either way, an Open Host Controller Interface (OHCI) is integrated which provides low-speed (1.5 Mbps), full-speed (12 Mbps), or hi-speed (480 Mbps) serial communications. Up to 127 USB devices (e.g. printer, mouse, keyboard, camera, usb adapters) and USB hubs can be connected to the USB host in the USB tiered-star topology. The USB device port provides USB gadget support such as mass storage device or IP over USB (aka Ethernet over USB, which effectively provides yet another Ethernet connection for the TS-SOCKET Baseboard). For more information regarding the features and setup instructions of the USB device port, refer to 4.12 USB Device Port Example Usage.

NOTE:

The Linux kernel implements all the necessary driver support to enable the USB OHCI and USB gadget features. Also, a wide variety of USB drivers for devices such as mouse, keyboard, cameras, flash memory, etc. are available through third-party resources or as options in the Linux kernel configuration.

3.4 XNAND Drive

APPLICABLE PRODUCTS: TS-4500, TS-4200, TS-4700, TS-4800

Technologic Systems XNAND technology is a user-space device driver that uses a simple RAID algorithm, Reed-Solomon codes, and extra checksums to allow any Linux filesystem to be used with confidence on NAND flash. The result is a rugged non-volatile storage device with industrial grade flash reliability. Our TS-BOOTROM also boots from XNAND for an ultra-reliable bootup.

XNAND Drive capacity depends on the TS-SOCKET Macrocontroller and options ordered. For example, the TS-4200 offers a 256 MB XNAND Drive (SLC NAND flash). Future products will offer greater than 1 GB XNAND Drives (MLC NAND flash).

Please refer to our Technologic Systems XNAND whitepaper for more information.

3.5 microSD Card Connector

APPLICABLE PRODUCTS: TS-4500, TS-4200, TS-4700, TS-4800, TS-8200

The microSD card socket (ALPS connector) enables microSD cards to be used as primary storage devices for the TS-SOCKET Macrocontroller. In some cases, the hardware core has been implemented by Technologic Systems and is integrated inside the on-board FPGA. In other cases, the hardware core is integrated inside the CPU. Refer to the specific TS-SOCKET Macrocontroller manual for more information regarding how the microSD card is accessed (via Linux driver or network block device) as well as partitioning information of the microSD card itself.

4 TS-SOCKET Software Guide

This purpose of this chapter is to touch upon some of the most common Linux software and usage cases such as program development, cross compiling (kernel and software), network settings, as well as others. For the most part, it assumes that you have a Linux development PC or virtual machine separate from the TS-SOCKET Macrocontroller using a Debian based distribution (other distributions will work, just be aware of the differences like apt-get vs yum). There are methods of using Linux type commands from within a Windows environment such as Cygwin, but this has not been tested.

This is provided to Technologic Systems customers in hopes that it will be useful. Generally, such topics as custom kernel compilation are considered to be outside of the scope of Technologic Systems free technical support. Should you need additional support, Technologic Systems are available for custom engineering.

Remember that 1.) over time, files and paths may change, and 2.) you should always have a backup plan for restoring anything that may have been botched.

4.1 Connecting via Serial Console

Connecting to the TS-7500 is done by connecting a RS-232 NULL Modem cable from a development PC running either Linux or Windows to the COM port of the TS-752 development board. If using Windows, PuTTY or Hyperterminal are suggested. If using Linux, minicom is suggested. Whichever program is chosen, these settings are required to connect:

  • Bps/Par/Bits : 115200 8N1
  • Hardware Flow Control : No
  • Software Flow Control : No

Power on the board, and you should see the boot-up in progress and then the initrd/busybox terminal prompt (within 2 seconds).

If using minicom for Linux, you'll need to modify and save the default configuration page (the created configuration file is generally placed directly into /etc. Do to this, follow these instructions (in terminal):

   1.) apt-get install minicom     [IF NOT YET INSTALLED]
   2.) minicom -s
   3.) [Navigate to 'serial port setup']
   4.) [Type "a" and change location of serial device to '/dev/ttyS0' then hit "enter"]
   5.) [If needed, modify the settings to match this and hit "esc" when done]
      E - Bps/Par/Bits          : 115200 8N1
      F - Hardware Flow Control : No
      G - Software Flow Control : No
   6.) [Navigate to 'Save setup as dfl', hit "enter", and then "esc"]

To use minicom, simply type "minicom" in the terminal and power on the board (you'll need to be root (sudo or su)). You should now see:

   >> TS-BOOTROM - built Oct  1 2008                                               
   >> Copyright (c) 2008, Technologic Systems                                      
   >> Booting from SD card...

Press "Ctrl + A" then "Z" to get the minicom command menu. For example, hitting "Ctrl + A" then "Q" will quit the application and return you to the terminal.

4.2 Connecting via SSH or Telnet

This section will not be comprehensive as to avoid duplicating any documentation which can already be found online or otherwise. To connect via secure shell (SSH), you'll need to setup a password for root since SSH will not allow connections without a password. Use the passwd command to set a password. To connect via SSH in Windows, use an application like PuTTY (which also has telnet support). To connect in Linux, use ssh in the terminal after verifying that you have connectivity using ping. For example: ssh root@192.168.0.50. Likewise, use telnet command for telnet. You may need to change the IP address of the board for it to be recognized on your subnet (common subnet is 192.168.1.xx for example).

If you are having difficulties in using telnet, make sure that 1.) your serial console device (ie. ttyAM0) is listed in /etc/securetty and 2.) the following line is in the /etc/fstab file:

   devpts         /dev/pts    devpts     gid=4,mode=620 0    0

4.3 Common Debian Linux Commands and Files

This section will briefly mention some of the most commonly used utilities and files in an embedded Debian environment. If needed, the "Debian GNU/Linux Reference Card" and the Debian home page are great resources for getting started with Debian.

Logging In

After the desired Linux Kernel is loaded and executed, the file system loads and networking, logging, Apache web server, etc. are all started. When the login prompt is displayed, type root to login, with no password. A Bash login prompt will then appear. At this point, you are ready to enjoy your TS-SOCKET Macrocontroller running Linux.

Shutdown

Use the shutdown -h now command to halt the Linux system when running from SD or USB memory card to avoid corruption issues. The SD card is formatted with a journaled filesystem and are highly tolerant of improper shutdown sequences. The shutdown or poweroff commands are not required but still recommended.

Debian apt-get

When using the Debian Linux file system, adding new packages and removing undesired ones is done all through Debian's package management. apt, dpkg, all behave as expected. With Debian, one can easily install and remove software packages. For a quick demonstration of how easy it is to remove and install programs with Debian, try the following commands:

   apt-get update
   apt-get install hexedit
   hexedit /etc/passwd
   ^C (hit CTRL+C to safely exit)
   apt-get remove hexedit

Disk and Memory Usage Information

   * df -h
      -- Human readable info on space utilization of the SD Card/Filesystem
   * free 
      -- Info on memory/swap usage
   * ps; top; jobs
      -- Provide info about which programs are running (ie. ps aux)
   * mount -o remount,rw /mnt/root
      -- Remount /mnt/root with readwrite permissions (ro for readonly)
   * umount /dev/sda1
      -- Unmount partition 1 of the device at /dev/sda
   * /proc/mounts
      -- File contains additional information about disks

Linux Startup and Shutdown

   * /etc/init.d/
      -- Initialization scripts
   * runlevel
      -- Display default runlevel (also found in /etc/inittab)
   * /etc/rcX.d/XXXxxxxx
      -- Default runlevel scripts ran on system startup (ie. /etc/rc2.d/S99run)
   * /etc/rc0.d/XXXxxxxx
      -- Runlevel 0 (shutdown) scripts ran on system shutdown
   * shutdown -h now; shutdown -r now
      -- Shutdown or restart the system
   * /etc/fstab
      -- Disks mounted on startup
   * /etc/modules
      -- Modules inserted on startup

Navigation of Filesystem

   * ls
      -- List files in directory (use ls -la for more info)
   * cd /dir
      -- Change to directory /dir
   * mkdir /dir
      -- Make directory /dir
   * find /dir -name "*file*"
      -- Locate files in /dir with any filename containing the text "file"
   * echo $PATH
      -- Display where utilities are located
   * /lib/modules/`uname -r`/drivers
      -- Kernel modules and drivers location

System Information

   * dmesg
      -- System messages and logs (see also "/var/log/syslog")
   * ldd --version; gcc --version; /lib/libc.so.6
      -- Linker, Compiler, and other information about compiling environment
   * lsusb
      -- List all USB devices (additional info in /proc/bus/usb)
   * /etc/passwd; /etc/shadow
      -- Contains password information.  Remove second field of the line
         containing "root" delimited by ":" to clear password.
   * history
      -- Display recently used commands
   * man
      -- Manual for programs (ie. man ls)

System Configuration

   * date -s "3 DEC 2009 14:18:00"
      -- Set the time and date (hwclock --systohc will set RTC if available)
      -- Use 'cal' to view calendar
   * ifconfig eth0 192.168.1.111
      -- Set the IP address of eth0 to 192.168.1.111
   * apt-get install package
      -- Install package from Debian repositories
   * dhclient eth0; pump; udhcpc
      -- Obtain an IP address via DHCP
   * /etc/network/interfaces
      -- Network interface configuration
   * /etc/inittab
      -- Describes which processes are started at bootup and during normal 
         operation

Working with Files

   * touch filename
      -- Create a file called filename
   * cat filename; more filename; less filename; head filename; tail filename
      -- View contents of filename
   * cp source/file destination/file
      -- Copy file from source to destination
   * mv source/file destination/file
      -- Move file from source to destination
   * diff file1 file2
      -- View differences between file1 and file2 (use diff -u for cleaner out)
   * cmp file1 file2
      -- Compare two files
   * grep -r string /dir
      -- Recursively search for files in /dir which contain "string"
   * hexdump
      -- Dump ascii, decimal, hexadecimal, octal to terminal
   * sync
      -- Commit any data residing in cache to the disk (SD card). Use liberally.
   * vi; nano; pico
      -- Command line based text editors
   * tar xzvf filename.tar.gz -C /dir ; tar xjvf filename.tar.bz2 -C /dir
      -- Extract a tar.gz file to /dir ; Extract a tar.bz2 file to /dir
   * tar czvf filename.tar.gz /dir ; tar xjvf filename.tar.bz2 /dir
      -- Create a tar.gz file from contents of /dir; create tar.bz2 file from...
   * ftp
      -- File transfer protocol program to download FTP files
   * wget http://www.web.com/filename
      -- Get file from URL (also works with ftp sites)
   * scp root@192.168.1.100:/share/filename /dir
      -- Copy via SSH file filename from user@IP:/share to /dir

Working with Kernel Modules/Drivers

   * insmod module.ko
      -- Manually insert kernel modules (simple; dependency unaware)
   * depmod -a
      -- Build modprobe a list of all modules and dependencies
   * modprobe module
      -- Insert module and any dependencies
   * lsmod
      -- List all inserted modules
   * rmmod module
      -- Remove module from kernel

apt-get install installs a package name, while apt-get remove removes the named package. Visit the Debian home page for further information, since a full in-depth discussion on Debian is outside the scope of this document.

4.4 Setup a Dynamic/Static IP Address

You can change the default IP address of 192.168.0.50. If you're interested in setting up a dynamic IP address, simply use the dhclient from within Debian or udhcpc from within the busybox/fastboot environment. If you'd like a bit more control over the IP address, you can set up a static IP address. From within Debian, edit /etc/network/interfaces to reflect the changes you'd like to make:

   # Used by ifup(8) and ifdown(8). See the interfaces(5) man page or
   # /usr/share/doc/ifupdown/examples for more information.

   auto eth0
   #iface eth0 inet dhcp
   iface eth0 inet static
           address 192.168.1.100
           network 192.168.1.0
           netmask 255.255.255.0
           broadcast 192.168.1.255
           gateway 192.168.1.1


   #auto eth1
   #iface eth1 inet dhcp

Then, edit the /etc/resolv.conf file to reflect working DNS servers:

   nameserver 208.67.222.222
   nameserver 208.67.220.220

Now, reset the eth0 interface by using ifdown eth0; ifup eth0. Test the connection by using ping google.com.

4.5 Developing on Board

One of the most common ways to develop applications for the TS-SOCKET Macrocontroller is on the board itself using an editor such as vi or nano. vi can be difficult to understand at first, so refer to vi documentation which can be found through an Internet search (the results of learning it can be quite rewarding). You may also use any other CLI editors of your choosing such as emacs, pico, nano, etc.

Development of a simple .c or .cpp file can be compiled directly on the board by issuing gcc -Wall -mcpu=arm9 tstest.c -o tstest.

  • gcc = C compiler (use gpp for C++ compiler)
  • Wall = print out all warning messages
  • mcpu=arm9 = specify architecture (may vary between processors)
  • tstest.c = file to compile
  • -o tstest = output file name

Possibly the best way to develop applications is by using a Linux box with an NFS share setup which the board can access (Linux Journal has a guide on how to do this entitled "Starting Share Files with NFS"). This way, development can occur from the Linux box with a full GUI and be quickly compiled and ran directly from the fastboot/initrd environment without the need to transfer files. Here is the brief set of commands to run after setting up the NFS server in order to access the NFS share and start developing:

   # On-Board development from initrd/fastboot environment
   # Requires NFS server

   udhcpc
   mkdir -p /mnt/root/mnt2
   mount -o nolock,vers=2 192.168.1.101:/home/username /mnt/root/mnt2/
   chroot /mnt/root
   mount /proc
   cd mnt2/

   #EXAMPLE:
   #gcc -g -mcpu=arm9 gettemp.c sbus.c -o gettemp

Another way is to simply transfer files from the development PC to the board via FTP (username: eclipse; password: eclipse) and then compile on board. Most Linux distributions have ftp installed already. Here is an example dialog from a Linux box which transfers a test file to and from a TS-SOCKET Macrocontroller within the Debian environment:

   
   [user@linux ~]$ ftp 192.168.0.50
   Connected to 192.168.0.50 (192.168.0.50).
   220 ts7500 FTP server (Version 6.4/OpenBSD/Linux-ftpd-0.17) ready.
   Name (192.168.0.50:user): eclipse

   331 Password required for eclipse.
   Password: eclipse
   230- Linux ts7500 2.6.24.4 #55 Fri Aug 7 11:20:02 MST 2009 armv4l
   230- 
   230- The programs included with the Debian GNU/Linux system are free software;
   230- the exact distribution terms for each program are described in the
   230- individual files in /usr/share/doc/*/copyright.
   230- 
   230- Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
   230- permitted by applicable law.
   230 User eclipse logged in.
   Remote system type is UNIX.
   Using binary mode to transfer files.
   ftp> send test.c

   local: test.c remote: test.c
   227 Entering Passive Mode (192,168,0,50,169,248)
   150 Opening BINARY mode data connection for 'test.c'.
   226 Transfer complete.
   19914 bytes sent in 0.00399 secs (4994.73 Kbytes/sec)
   ftp> get test.c
   local: test.c remote: test.c
   227 Entering Passive Mode (192,168,0,50,218,4)
   150 Opening BINARY mode data connection for 'test.c' (19914 bytes).
   226 Transfer complete.
   19914 bytes received in 0.00578 secs (3447.71 Kbytes/sec)
   ftp> bye

   221 Goodbye.
   [user@linux ~]$ 

4.6 Modifying/Adding Files (microSD)

Most development can be completed directly from the board, but it might not be as efficient or simple as modifying or adding the files directly on a separate development PC with a Linux OS. To do this, insert the microSD card into the SD card adapter and then insert the SD Card adapter into the USB SD card reader. The Linux system will probably try to automatically mount the partitions. This might work for some users, but a good habit would be to manually mount the partitions to a known directory. Here is one way to do this and then start editing a file (all done in terminal on Linux PC):

   1.) mkdir /mnt/part4
   2.) mount -t ext3 /dev/sdb4 /mnt/part4 [verify /dev/ location with 'fdisk -l']
   3.) cd /mnt/part4
   4.) vi linuxrc  [you may use an editor of your choice like gedit]

Other partitions of interest would be partition 1 and 3, in which case you'll repeat the steps 1-3 above with the new partition number.

There are several other methods to transfer files including USB thumb drives, FTP, NFS, Samba, etc. Some of these methods have been discussed already in the 3.5 Developing on Board section above.

4.7 Fixing microSD Card Corruption

Technologic Systems carefully chooses the type of filesystems in which to use in any of their products, however, no filesystem is perfect. They are all susceptible to becoming dirty with filesystem corruption. Symptoms include long boot times and/or the Linux development PC not being able to identify or mount the partitions (both nonfs and ext3) when the microSD card is inserted into the USB SD Card reader. Most of the time this is easily fixed by running, for example, "fsck /dev/sdb4" on the Linux development PC.

4.8 Simple Cross Compiling Example

The following steps have not been verified and are only presented to demonstrate correct principles!

The following is a step-by-step guide to compiling a simple C++ program for use in the Debian environment. These steps have been verified on a TS-4500 and should work for any of the TS-SOCKET Macrocontrollers with the caveat that toolchains might differ slightly. For example, if you would like to compile an application for the busybox environment for the TS-4500, you'll simply need to replace the glibc crosstools with the uclibc crosstools located here and keep in mind that the crosstool directory structure is a little different. Also, for compiling a C program, replace 'g++' with 'gcc'. The same is also true for other compilers.

   Assumptions:
      -- The cross compiler will be located at ~/crosstool (~ is equivalent to $HOME)
	     * mkdir ~/crosstool/   
      -- The program will be located at ~/main.cpp

   01.) Download the cross compile toolchain (EABI)from Technologic Systems:
      *  wget ftp://ftp.embeddedarm.com/ts-arm-sbc/ts-7200-linux/cross-toolchains/crosstool-linux-gcc-4.0.1-glibc-2.3.5.tar.bz2

   02.) Extract to crosstool directory:
      * tar xvf crosstool-linux-gcc-4.0.1-glibc-2.3.5.tar.bz2 -C ~/crosstool

   03.) For cleanliness sake, delete the originally downloaded tar.gz file:
      * rm crosstool-linux-gcc-4.0.1-glibc-2.3.5.tar.bz2

   04.) Change directory to where your program is located:
      * cd ~
      
   05.) Use the following greatest common divisor (gcd.cpp) file as an example if 
	    needed:

   =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

     #include <iostream>
     using namespace std;

     int GCD(int a, int b)
     {
         while( 1 )
         {
             a = a % b;
		     if( a == 0 )
			     return b;
		     b = b % a;

             if( b == 0 )
			     return a;
         }
     }

     int main()
     {
	     int x, y;

	     cout << "This program allows calculating the GCD\n";
	     cout << "Value 1: ";
	     cin >> x;
	     cout << "Value 2: ";
	     cin >> y;

	     cout << "\nThe Greatest Common Divisor of "
	          << x << " and " << y << " is " << GCD(x, y) << endl;  

	     return 0;
     }

   =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

   06.) Use the cross compiling toolchain to compile the program:
      * ./crosstool/opt/crosstool/gcc-4.0.1-glibc-2.3.5/arm-unknown-linux-gnu/bin/arm-unknown-linux-gnu-g++ gcd.cpp -o gcd

   07.) Copy the program to the TS-75XX and then test by running it.  You will see:

        ts7500:~# ./gcd 
        This program allows calculating the GCD
        Value 1: 8
        Value 2: 2

        The Greatest Common Divisor of 8 and 2 is 2
        ts7500:~# 

   08.) Additionally, you can include the crosstools in your PATH for less typing:
      * PATH=$HOME/crosstool/opt/crosstool/gcc-4.0.1-glibc-2.3.5/arm-unknown-linux-gnu/bin/:$PATH
      * export PATH
      * arm-linux-uclibc-g++ gcd.cpp -o gcd

4.9 Compiling Linux Kernel with Custom Options

The following steps have not been verified and are only presented to demonstrate correct principles!

The following is a verified step-by-step guide to compiling a custom Linux kernel specifically for the TS-7500. Although it has not been written specifically for the TS-SOCKET Macrocontrollers (yet) , the principles described below are still just as valid. This was written with beginners in mind, but may still be a bit too advanced for some. Remember to backup file and images so you may revert back to them if something goes wrong.

Warning:

BACKUP YOUR FILES AND IMAGES!

Prerequisites:

SOFTWARE:

  • Must be logged in as root on a Linux PC separate from the SBC
  • These packages need to be installed for kernel compiling:

    RHEL/Fedora/CentOS:
    yum install ncurses-devel ncurses
    Debian/Ubuntu:
    sudo apt-get install libncurses5-dev libncursesw5-dev

HARDWARE:

  • TS-7500 SBC with 2GB MicroSD Card inserted
  • TS-752 Development Board Connected with JP1 = OFF; JP2 = ON (Offboard SPI)
  • MicroSD Card Adapter and USB SD Card Reader
  • Development PC with Linux installed

Procedure:

  
   01.) Download the cross compile toolchain (OABI)from Technologic Systems:
      * wget ftp://ftp.embeddedarm.com/ts-arm-sbc/ts-7500-linux/cross-toolchains/crosstool-linux-arm-uclibc-3.4.6.tar.gz

   02.) Extract to current working directory:
      * tar xvf crosstool-linux-arm-uclibc-3.4.6.tar.gz

   03.) Obtain the TS-7500 kernel source tree
      * wget ftp://ftp.embeddedarm.com/ts-arm-sbc/ts-7500-linux/sources/linux-2.6.24-ts-src-aug102009.tar.gz

   04.) Extract the TS-7500 kernel source tree
      * gzip -dc linux-2.6.24-ts-src-aug102009.tar.gz | tar xf -

   05.) Move into the newly extracted directory
      * cd linux-2.6.24-cavium/

   06.) Edit the Makefile at the kernel root dir to point to the appropriate 
        cross-compiler path.  In our case, with the toolchain decompressed into 
        the same directory as the kernel, we'll change line 195 of the Makefile 
        to read:
      * CROSS_COMPILE ?= ../arm-uclibc-3.4.6/bin/arm-linux-

   07.) Type "make ts7500_defconfig" to make the kernel with the options that 
        Technologic Systems uses for the TS-7500

   08.) Type "make menuconfig" and edit the boot command line and other options 
        of interest (optional)
      * For Example, to include CIFS support, use the arrow and Enter keys to 
        navigate to Filesystems -> Network File Systems -> CIFS Support.  Press 
        "y" to include CIFS support into the kernel (alternatively, you could 
        modularize the feature with "m" so you can enable or disable the module 
        on demand which will also enable you to simply copy/paste the cifs.ko 
        into the correct path in the kernel instead of copying the entire kernel 
        (outlined below in appendix)).  Keep hitting "exit" until you're 
        prompted to save changes, choose "yes".

   09.) Type "make" to compile the kernel

   10.) The new kernel will be at "arch/arm/boot" in a compressed format called 
        zImage (the uncompressed version is simply called Image, but it is 
        REQUIRED that it be < 2096640 bytes in size).

   11.) Copy the binary zImage to the second partition (in most cases, this is 
        mounted as /dev/sdb2).  This will erase any data which is on the MiniSD 
        card now, so a backup is advised.
      * TO BACKUP: dd if=/dev/sdb2 of=../zImageBak
      * TO COPY zImage: dd if=arch/arm/boot/zImage of=/dev/sdb2

   12.) At this point, insert the MiniSD card and try to boot.  If the image is 
        working correctly, and you'd like to be able to use the TS-7500 
        independently of the TS-752 development board, you will need to copy the 
        kernel to the 4MB SPI Flash on the board, as it will boot from SPI 
        Flash instead of MiniSD without the development board.
      * mkdir /temp
      * dd if=/dev/nbd2 of=/temp/zImage
      * dd if=/dev/nbd3 of=/temp/initrd
      * spiflashctl -W 4095 -z 512 -k part1 -i /temp/zImage
      * spiflashctl -W 32 -z 65536 -k part2 -i /temp/initrd
      * sync

   13.) Test by placing both JP1 and JP2 to the OFF position.  You should have 
        ">> Booting from onboard SPI flash..." and the system should boot as 
        expected.
        

Compiling TS-Kernel with Custom Options

In order to compile a separate kernel module and come out with a *.ko file for inclusion in the already existing kernel, these are the steps to take following step 08 and ending at step 09 above. Note: Steps after step 02 are unverified/untested. They represent an accurate procedure which one would go through.

   01.) Open menuconfig and modularize the kernel feature using "M".  For 
        example, to modularize cifs.ko, one would use the arrow and Enter keys 
        to navigate to Filesystems -> Network File Systems -> CIFS Support.  
        Press "M" to modularize CIFS support into the kernel then keep hitting 
        "exit" until you're prompted to save changes, choose "yes".
      * make menuconfig
      
   02.) Compile the kernel with the modules and copy the modules to the Linux PC
      * make && make modules && make modules_install  
      
   03.) Retrieve the module which was copied to the Linux PC with a command like
        cp so that it can be installed into the kernel on the MiniSD card.
      * mkdir /mnt/miniSD4
      * mount /dev/sdb4 /mnt/miniSD4
      * cp /lib/modules/2.6.24.4/kernel/fs/cifs/cifs.ko /mnt/miniSD4
      
   04.) Install the module into the kernel by copy and pasting from partition 4 
        of the card to partition 2 on the SBC.
      * cp -r /dev/nbd4/cifs.ko /dev/nbd2/lib/modules/2.6.24.4/kernel/fs/cifs/cifs.ko

    05.) Finally, in order to use the new module, you must enable it.  This can 
         be included in a startup script such as linuxrc.
      * depmod
      * modprobe cifs.ko

Troubleshooting insmod or modprobe Errors

If you're having difficulties inserting your module (ie. "insmod: error inserting module.ko: -1 Invalid module format"), it could be because either 1.) the kernel which it was compiled against has not been loaded to the microSD and/or 2.) there are module dependencies that are not being satisfied. The dmesg utility is invaluable when trying to troubleshoot these issues.

When compiling additional modules into the kernel, you must use make modules_install as the final step in kernel compiling to install the modules to your development Linux PC. From there, you can create a tarball to copy and then extract to the fourth partition of the microSD card. ie. (assuming your microSD card's device node was enumerated to /dev/sdb; use fdisk -l to verify)

   
   tar czvf linuxmodules-2.6.24.tar.gz /lib/modules/2.6.24.4/
   mkdir /mnt/sd_part4
   mount /dev/sdb4 /mnt/sd_part4
   tar xzvf linuxmodules-2.6.24.tar.gz -C /mnt/sd_part4/

After doing this, boot the TS-7500 with the updated microSD card to full Debian and then can use depmod -a to build the module dependency lists that modprobe will use. Once this has been complete, you should then be able to use modprobe to successfully insert the module along with all of its dependencies. ie.

   modprobe usbnet

If you would like your module to be inserted automatically on system startup, then simply include the module name in /etc/modules. ie.

   echo "usbnet" >> /etc/modules

Keep in mind that if anything in the make menuconfig step was required to be compiled as part of the kernel as indicated by [*], then you will need to copy the entire kernel image to the microSD card. ie.

   dd if=arch/arm/boot/Image of=/dev/sdb2

4.10 USB to Serial Devices

The following steps have not been verified and are only presented to demonstrate correct principles!

Additional serial ports can be added to the TS-SOCKET Macrocontrollers by using USB to Serial cables through the USB Ports (and even more if a USB hub is used). You will need three modules, all of which are loaded by default. If you are having difficulties locating these drivers, contact Technologic Systems.

   01.) Insert the necessary modules
        * insmod /lib/modules/`uname -r`/kernel/drivers/usb/host/ohci-hcd.ko
        * insmod /lib/modules/`uname -r`/kernel/drivers/usb/serial/usbserial.ko
        * insmod /lib/modules/`uname -r`/kernel/drivers/usb/serial/ftdi_sio.ko
   02.) The kernel should then detect the FTDI device and add device node at
          /dev/ttyUSB0

After successfully installing the USB to Serial adapter, you can then use minicom as described in 3.1 Connecting via Serial Console above.

4.11 Load Scripts/Programs Automatically on Bootup

Scripts and/or programs can be run automatically as part of the Linux bootup process by adding it to the /etc/rc2.d runtime folder. For example, if you wanted to immediately print out the IP address on boot, you would follow these simple steps:

   01.) echo "ifconfig eth0" > /etc/init.d/displayip
   02.) chmod +x /etc/init.d/displayip
   03.) ln -sf /etc/init.d/displayip /etc/rc2.d/S01displayip
           * Note: you may need to check your default runlevel with the
             'runlevel' command (default from Technologic Systems is 2)

If you find that your process is being killed, try preceding it with the 'nohup' command, followed by a 'sleep 1' command. For example:

   #!/bin/sh

   echo -n "Initializing my program..."
   nohup myprogram --daemonize &
   sleep 1
   echo "done"

4.12 USB Device Port Example Usage

The following steps have not been verified and are only presented to demonstrate correct principles!

Certain Technologic System Single Board Computers (SBCs) contain both USB Host and USB Device ports. This section will discuss the configuration and use of the Linux USB device gadgets (http://www.linux-usb.org/). The two supported gadgets are 1) USB Mass Storage Device and 2) IP over USB (A.K.A. USB Ethernet).

The USB Mass Storage Device Linux USB gadget will allow you to use your SBC as a storage device, like a USB thumb drive, when connected to a host PC. Subsequently, the SBC can access the saved data through the storage element named usb_storage_file.

The IP over USB (A.K.A. USB Ethernet) Linux USB gadget will allow you to connect to your SBC with a USB cable from a PC like you would with a CAT5 Ethernet cable. You will have access to the SBC via the TCP/IP connection allowing you to use any networking utility (e.g. ping, ssh, ftp, http, etc).

All software modules required for Linux are contained on recent SBCs (those released with the May 18, 2010 or later software load). For Windows, a driver interface configuration file (linux.inf) will need to be downloaded and installed on the host PC. This procedure is described in detail below.

Utilizing SBC as "USB Mass Storage Device"

The SBC must be setup prior to connection to a host PC. These steps are outline below. These steps assume that the g_ether module is unloaded (rmmod g_ether).

   1.) Create a mount point and then mount the first partition of SD card where
       the storage element exists.
      * mkdir /mnt/vfat; mount /dev/nbd1 /mnt/vfat

   2.) Install the g_file_storage driver with storage element details
      * modprobe g_file_storage file=/mnt/vfat/usb_storage_file

After following these steps for preparing the SBC storage element, plug the SBC into the host PC with a A to B USB Cable (ISB Cable). You will see the newly mounted volume and should be able to access it.

When you have completed using the device on the Linux or Windows System, you will need to eject volume using either umount on Linux, or "Safely Remove Hardware" on Windows and then unplug the USB cable.

After transferring data from a host PC to the SBC through the USB Mass Storage Device Linux gadget, you can access the data on the SBC by using the following steps.

   1.) Remove the g_file_storage driver allowing local access to storage element
      * rmmod g_file_storage

   2.) Create a mount point and then mount the storage element (assuming
       "/dev/nbd1" is still mounted to "/mnt/vfat" from steps above)
      * mkdir /mnt/usbdev
      * mount -t vfat -o loop=/dev/loop0,offset=4096 /mnt/vfat/usb_storage_file /mnt/usbdev/
NOTE:

The kernel should already have support for loop block devices. If not, you will need to insert the loop.ko module with modprobe or insmod.

You can now locally access /mnt/usbdev.

When finished with the device, or to allow access via the USB Device port, you must un-mount the device using:

   umount /mnt/usbdev

Utilizing IP over USB (USB Ethernet) on SBC

The SBC must be setup prior to connection to a host PC. These steps are outline below.

   1.) Install the g_ether driver
      * modprobe g_ether

   2.) Assign an IP address to the new usb0 interface
      * ifconfig usb0 192.168.42.20
NOTE:

The IP address in the above example may be any valid IP address, but should typically not be on the same subnet as the Ethernet network on the SBC (if connected), or the host computer to which the SBC will be connected.

Connecting Linux Host to SBC via IP over USB

Most modern Linux distributions already have all of the required modules (i.e. usbnet.ko) and utilities installed, so the setup steps are minimal. Simply plug in the SBC after it has been prepared for IP over USB (see above) and observe that a new interface has been added named usb0 or similar (use dmesg | tail to verify). You can now assign an IP address to that interface with ifconfig (e.g. ifconfig usb0 192.168.42.21) and begin using the TCP/IP connection. To test your connection, use ping 192.168.42.20. You should also be able to login to the SBC using ssh ie. ssh root@192.168.42.40.

NOTE:

The IP address above may be any valid IP address, but must be in the same subnet as the IP address assigned to the SBC IP over USB connection above.

Connecting Windows XP Host to SBC via IP over USB

An additional driver interface configuration file called linux.inf is required for IP over USB connection to a Windows host. First, download this file onto the Windows PC and remember where you placed it. Next, connect the SBC and Windows PC with the A to B USB cable (ISB Cable). You should see the "Found New Hardware Wizard". Answer the prompts as follows:

  1. Select Include this location in the search and choose the location of the driver you downloaded. Finish running the wizard.
  2. Go to the Control Panel and open "Network Connections". Right-click the new connection (labeled "Linux USB Ethernet/RNDIS Gadget") and click "Rename". Rename it to something useful such as "USB Network".
  3. Right-click on the newly labeled icon, and select properties.
  4. Under the properties General tab, select the item labeled Internet Protocol (TCP/IP)
  5. Select Use the following IP Address, and enter 192.168.42.21.
  6. Click OK; Click OK

You may now access the SBC via the TCP/IP connection. Use ping in the Command Prompt window to verify connectivity (e.g. ping 192.168.42.20).

NOTE:

Note that the IP address above may be any valid IP address, but must be in the same subnet as the IP address assigned to the SBC IP over USB connection above.

Connecting Windows Vista Host to SBC via IP over USB

Not yet supported, but currently in progress.

Connecting Windows 7 Host to SBC via IP over USB

Not yet supported, but currently in progress.

5 TS-SOCKET Common Pinouts

All offboard connections on any TS-SOCKET Macrocontroller module go through the 2 high density 100 pin board to board connectors CN1 and CN2. The mating connectors and mechanical layout specification are available from the TS website. The following tables list the pins along with their pin name and/or functions that are common for all TS-SOCKET Macrocontrollers.

Left Connector (CN1)

Pin # Name Function Pin # Name Function
1 FPGA_JTAG_TMS JTAG interface for FPGA, 4.7k pull up 2 EXT_RESET# Input used to reboot TS-4500
3 FPGA_JTAG_CLK JTAG interface for FPGA, 4.7k pull up 4 EN_USB_5V USB 5V enable output
5 FPGA_JTAG_TDO JTAG interface for FPGA 6 SDCARD_D2 SD data bus, in parallel with onboard SD
7 FPGA_JTAG_TDI JTAG interface for FPGA, 4.7k pull up 8 SDCARD_D3 SD data bus, in parallel with onboard SD
9 OFF_BD_RESET# Off board reset output, asserted when board boots or reboots 10 SDCARD_CMD SD command IO, in parallel with onboard SD
11 12 SDCARD_3.3V SD card power
13 14 SDCARD_CLK SD card clock
15 POWER Board Power 16 POWER Board Power
17 18 SDCARD_D0 SD data bus, in parallel with onboard SD
19 20 SDCARD_D1 SD data bus, in parallel with onboard SD
21 22
23 24
25 26
27 28
29 POWER Board Power 30
31 32
33 34
35 36 V_BAT RTC Battery voltage
37 38
39 40
41 42
43 44
45 46
47 POWER Board 5V power 48
49 50
51 52
53 54
55 56
57 58
59 60
61 62 GND Ground
63 DIO_14 FPGA DIO 64
65 DIO_13 FPGA DIO 66
67 DIO_12 FPGA DIO 68
69 DIO_11 FPGA DIO 70
71 DIO_10 FPGA DIO 72
73 DIO_9 FPGA DIO 74
75 GND Ground 76
77 DIO_8 FPGA DIO 78
79 DIO_07 FPGA DIO 80
81 DIO_06 FPGA DIO 82
83 DIO_5 FPGA DIO 84
85 DIO_4 FPGA DIO 86
87 DIO_3 FPGA DIO 88
89 DIO_2 FPGA DIO 90
91 DIO_1 FPGA DIO 92
93 DIO_0 FPGA DIO 94
95 GND Ground 96
97 98
99 100
NOTE:

SD card signals on connector are wired in parallel with SD card socket. Only one can be populated with an SD card.

Right Connector (CN2)

Pin # Name Function Pin # Name Function
1 ETH_RX+ 10/100 Ethernet RX+ 2 ETH_LEFT_LED Ethernet jack left LED
3 ETH_RX- 10/100 Ethernet RX- 4 ETH_RIGHT_LED Ethernet jack right LED
5 ETH_CT Ethernet center tap 6 RED_LED# Red led output
7 ETH_TX+ 10/100 Ethernet TX+ 8 GREEN_LED# Green led output
9 ETH_TX- 10/100 Ethernet TX- 10
11 ETH_CT Ethernet center tap 12
13 14
15 16
17 18
19 20
21 22
23 24
25 26
27 28 TW_CLK DIO, CPU connected I2C SCL, 4.7k pull-up
29 HOSTA_USB_M Host USB port A 30 TW_DAT DIO, CPU connected I2C SDA, 4.7k pull-up
31 HOSTA_USB_P Host USB port A 32
33 34
35 HOSTB_USB_M Host USB port B 36
37 HOSTB_USB_P Host USB port B 38
39 3.3V 3.3V power (output from module) 40
41 42
43 44 CPU_JTAG_TMS CPU JTAG interface
45 GND Ground 46 CPU_JTAG_TCK CPU JTAG interface
47 48 CPU_JTAG_TDI CPU JTAG interface
49 50 CPU_JTAG_TDO CPU JTAG interface
51 GND Ground 52
53 54
55 56
57 1.8V 1.8V power (output from module) 58
59 60
61 62
63 64
65 SPI_CS0# SPI CS0#, weak FPGA pull-up 66
67 SPI_MOSI SPI master-out slave-in (output from module) 68
69 SPI_MISO SPI master-in slave-out (input to module) 70
71 SPI_CLK SPI clock (output from module) 72
73 GND Ground 74
75 76
77 78 Serial Ports or DIO
79 80 Serial Ports or DIO
81 82 Serial Ports or DIO
83 84 Serial Ports or DIO
85 86 Serial Ports or DIO
87 88 Serial Ports or DIO
89 90 Serial Ports or DIO
91 92 Serial Ports or DIO
93 DEBUG_TXD Serial console TX (TTL output) 94 Serial Ports or DIO
95 DEBUG_RXD Serial console RX (TTL input) 96 Serial Ports or DIO
97 98 Serial Ports or DIO
99 100 Serial Ports or DIO
NOTE:

Ethernet Magnetics should be placed as close to CN2 as possible on the baseboard.

Appendix A: Further References

Generic TS-SOCKET Resources

TS-SOCKET Macrocontroller Resources

TS-SOCKET Baseboard Resources

Appendix B: Revision History

Date of Issue/Revision Revision Number Comments
To Be Determined (TBD) 1.0 Released as TS-SOCKET Manual (Preliminary)