the LANCRE project

a firmware for c't magazine's MCU-in-LAN project

written by Christian Vogelgsang

under the GNU Public Licencse V2

3.4.2005

1. Introduction

The MCU-in-LAN project of the german c't magazine presents a small two circuit board HW system that provides a LAN connection, a serial COM port (RS232) and a small microcontroller (Atmel AVR mega8535 MCU). The main purpose of the LAN-COM board is to provide a gateway for legacy serial hardware and allow connection and control via Ethernet. Additionally, the MCU allows to perform processing of sensor data (e.g. temperature measurement), can cope with user input (4 keys) and has output facilities (4 LEDs and an optional LCD). The MCU can send and receive serial data either to/from the COM or the LAN port. If the COM and LAN port are connected directly, the MCU can sniff on one direction and copy the data that is transferred.

The LANCRE frimware presented here is the program code for the MCU ROM. The firmware assumes that you have connected a LCD (a 16x2 in my case) and optionally one or two sensors connected to the analog amplifiers accessed by the ADCs of the MCU. The firmware allows to control the serial connection type (COM to LAN, COM to MCU, LAN to MCU) and its parameters (e.g. baud rate) with the key panel. Furthermore, it sniffs on the COM to LAN connection for a special key word ("lc" + EOL as default). If this word occurs then the MCU automatically connects the sniffed source (either LAN or COM) and presents a command prompt. On the command prompt, the user can send control commands to the MCU that provide access to most low level hardware features of the MCU board (e.g. read/write ports), the LAN interface (set control pins) or the peripherals (read out ADC sensors and map them linearly).

2. Features

complete extensible and open firmware for the MCU
controls the serial connection (select source (COM/LAN) and its parameters (baud rate))
set parameters and modes easily with the key panel
gives feedback on the LED panel (for users without LCD)
verbose output is available on a LCD
sniff serial channel (links to MCU on special key word, copies all readable data on LCD)
toggle sniff and pass-through mode
link mode connects source with the MCU and provides a command shell
command shell allows to control the MCU and its peripherals
read/write MCU ports, set its directions
read ADCs of the MCU
map ADC values linearly to output range (useful for a temperature display)
calibrate the ADC mapping by providing to sample pairs (adc value, measurement)
setup and trigger control pins on XPort LAN controller
set all connection modes and parameters of the device on the command prompt
save/load parameters presistently to EEPROM

3. Download

3.1 Files

3.4.2005 Initial public release:
- lancre-0.9-src.tgz (source code)
- lancre-0.9.hex.gz (binary ROM image)

3.2 Requirments

If you want to compile the firmware yourself, you will need the following tools:

gcc-avr The GNU Compiler Collection for the AVR series (I use the Debian gcc-avr package. Windows users can use the WinAVR package) including GCC compiler, binutils, avr-libc and make.
Procyon AVRlib A very useful library for AVR development in C (Install the library source and adjust LANCRE's Makefile)

3.3 Burning the ROM

Use your favorite ISP-programmer to transfer the provided ROM image in Intel HEX format to your device. I use the AVRdude ISP programmer on linux. The provided Makefile in the source package has a "prog" rule to compile and transfer the firmware.

4. User's Manual

4.1 Definitions

4.1.1 Connection source and mode

The device provides three serial communications ports: the LAN (handled via the XPort device), the COM (RS232 connector on board) and the MCU (AVR mega8535). Two of these ports are always connected and the third one can sniff what one of them is sending. The port that is connected and will be sniffed is called the Source. Either LAN or COM can be the source, because sniffing is currently only used by the MCU.

Three connection modes are supported by the firmware: the sniff mode connects the LAN and the COM port and the MCU sniffs what the source (either COM or LAN) is sending. On receiption of a special key word ("lc" + EOL) the device changes to link mode. Then the MCU directly connects to the source and starts to communicate directly with this port. The MCU emits a command prompt and is ready to execute user commands. Finally, the pass-through mode is similar to the sniff mode, as it connects the COM and LAN port, but it does not sniff for the key word and is thus a totally transparent LAN-COM gateway.

4.2 Device Usage

The device can be controlled with the 4 keys located on the front side. Depending on the connection mode the device is currently in, the keys have different meanings. The associated LED panel is used to represent status information in the current mode. More information is available on a connected LCD. There state information is directly displayed.

Here is a list of the key panel commands:

Mode	Red Key	Orange Key	Yellow Key	Green Key
Sniff/Pass-Through	Enable Menu	Toggle Source: LAN or COM	Toggle Sniff/Pass-Through	Enable Link Mode
Link	Command 0	Command 1	Command 2	Leave Link Mode
Menu	Next Menu Entry	Decrease current value	Increase current value	Leave Menu

Depending on the current mode, the LED display is different:

Mode	Red LED	Orange LED	Yellow LED	Green LED
Sniff/Pass-Through	Source is COM	Source is LAN	On: Sniff mode Off: Pass-Through	Off: No Link
Link	OFF	OFF	OFF	On: Link Mode
Menu	LEDs display the current menu entries' value

Mode

Red LED

Orange LED

Yellow LED

Green LED

Sniff/Pass-Through

Source is COM

Source is LAN

On: Sniff mode

Off: Pass-Through

Off: No Link

Link

OFF

On: Link Mode

LEDs display the current menu entries' value

The LCD Display uses two rows:

In the first row, the current status is always displayed: First "XPort" or "RS232" denote the source of the connection (LAN or COM). Then "sniff", "pass" or "LINK" give the current connection mode. Finally, on the right side the baud rate of the MCU is given (9.6 meens 9.6 kbaud or 9600 baud). Always make sure to set the right baud rate here, otherwise communication with the source in link mode is not possible.
The second row of the display shows the data received or send by the MCU. In sniff mode you can see all characters transferred to the target. Only readable chars are printed otherwise '?' is emitted. Linefeeds or Delete characters are interpreted and change the displayed characters. If more characters are send in a line then are displayable on the LCD then the output is scrolled.
In link mode the second row of the display is used to display command input and output. First the command prompt '>' is displayed and then the MCU waits for user input. If a valid command is sent then the result of the command is displayed on the right side of this row starting with a '='.

4.3 Menu

The device menu displayed on the LCD allows to setup various parameters. Press the red key while the device is in sniff/pass-through mode. You can leave the menu by pressing the green key. The current menu entry is then displayed in the second row of the LCD and denoted with a '@'. By pressing the red key while in menu mode you can select the next menu entry. The orange and yellow key are used to alter the currently selected menu item. The yellow key increases the selected value and the orange key decreases it.

A list of available menu entries:

baud rate: change the baud rate of the MCU. Make sure to set the same value in your connected device *and* in the XPort if the source is LAN. For the XPort you can use either the configuration utility (windows only) provided by Lantronix or a text terminal connected at TCP port 9999 of the XPort. The currently selected baud rate is given in kbaud and displayed on the left side of the LCD's top row. Please note, the baud rate is changed not unitl the menu mode is left.
echo char: in link mode the MCU directly talks with the connected device. This is usually a terminal program operated by the user. The echo char menu item allows to control, if each received char from the user is transferred (echoed) back to his/her terminal. If you see nothing while you type then enable echoing. If you see each typed char twice then disable this mode. NOTE: If you use netcat or telnet to access the device then a line of characters is send after an EOL and not after each key press.
rx eol: this entry tells the device what characters form an EOL (end of line). Depending on your system a single return (CR), a single new line (LF) or both (CR+LF) is used to reach the beginning of a new line. CR is often used on Mac systems, LF on Unix/Linux and CR+LF on Windows machines. Nevertheless, your terminal program often also allows to control the EOL mode on each system separately. The rx denotes that this sequence is used for all data received by the MCU.
tx eol: similar to rx eol, you can now control how an EOL (end of line) will be transmitted by the MCU.
save/load: this is no ordinary menu item that alters a parameter. This mode allows to save or load the parameters from the internal EEPROM. Use the save command to make your settings persistent, i.e. they are available after a reset or a power-down. The save command is triggered by pressing the orange key and the load command is issued by the yellow key. A single beep acknowledges successfull storage. Multiple beeps signal an error. On power up, the EEPROM is usually invalid and thus a multiple beep is issued. Following this, a fresh and valid entry with default values is written.

4.4 Command List

In link mode, the following commands are accepted by the MCU. A command is a sequence of characters optionally followed by one or more parameters. Please note the case of the characters and that there are no spaces allowed between the characters and values. All value parameters are given as HEX numbers and require a fixed number of digits:

a <nibble> is a single 4 bit value given in hex by a digit 0...9 or character a...f, e.g. 0 1 e
a <byte> is a pair of nibbles (8 bit) and given by two valid hex characters, e.g. ab 01 00
a <word> is a four tuple of nibbles (16bit) and given by four hex characters, e.g. abcd 0123 ffef 01ab

Some commands are organized into groups where the first character selects the group and the following characters select a sub-command in the group.

Command/Group	Key Command	Description
q		Leave link mode and finish command mode (similar to pressing the green key in link mode)
x		Reset device and reinitialize it
v		Print the current version of LANCRE
b<n>		Beep <n> times
c		Configuration command group (see below)
p		Control AVR Ports (see below)
a<n>		Read ADC value of ADC<n>. n=0,1 are connected to the sensor inputs of the board
A	1 (orange key)	ADC summary. Show ADC values of ADC0 and ADC1
m<n>		measure ADC value and map result (see below)
M		map ADC value summary. Show mapped ADC0 and ADC1 values
d<n>		measure ADC value, map result and display in decimal
D	0 (red key)	map ADC value summary in decimal
g		Control Pins at XPort (see below)
G	2 (yellow key)	Control Pin summary. Show XPort CP direction and value for CP1, CP2 and CP3

4.5 Configuration Commands 'c'

Command	Example	Description
cS	cS	Write all settings to EEPROM
cL	cL	Load all settings from EEPROM
cs<n>	cs0	Set source port: 0=COM 1=LAN
cl<n>	cl1	Start device with link mode enabled=1 or disabled=0
ci<n>	ci0	Set sniff mode(1) or pass-through (0) mode
ce<n>	ce0	Set echo mode: 0=no echo, 1=echo
cr<n>	cr2	Set rx EOL: 0=LF, 1=CR, 2=CR+LF
ct<n>	ct1	Set tx EOL: 0=LF, 1=CR, 2=CR+LF
cb<n>	cb	Set Baud Rate 0: 9600, 1: 19200, 2: 38400, 3: 57600, 4: 115200
ck<string>	ckhello	Set a new key word for sniffing. All characters after the ck command are used. A rx EOL is always the end of the sniff key.
cmr<n><what>	cmr0a	Read ADC mapping ranges: <what> is a=ADC range, m=mapped range <n> is ADC port: 0,1
cmw<n><what><word1>,<word2>	cmw0a1234,5678	Write ADC mapping range: <what> is a=ADC range, m=mapped range <n> is ADC port: 0,1
cmr<what>	cmrl	Read Sample point for calibration: <what> is l=lower u=upper
cmw<what><word1>,<word2>	cmwl1234,5678	Set Sample point for calibration: <what> is l=lower u=upper <word1> is ADC value <word2> is mapped value
cmc<n>	cmc0	Perform calibration and setup the ADC mapping ranges with the two given sample points (lower and upper) <n> is ADC port: 0,1

You can use all configuration commands without parameters to see the current values.
Configuration values that alter the link state or the connection mode are enabled after leaving the command mode.

4.6 AVR Port Commands 'p'

Command	Example	Description
pr<P>	prc	Read 8 bit port: <P> is a,b,c or d
pw<P><bb>	pwa07	Write a byte <bb> to port <P>
pR<P>	pRb	Read data direction register of port <P>
pW<P><bb>	pWc18	Set data direction register of port (BIT: 1=output, 0=input)

4.7 XPort Control Pin Commmands 'g'

Command	Example	Description
gr<p>	gr1	Read control pin value of XPort CP<p> 1, 2, or 3
gw<p><n>	gw10	Set a control pin to <n>: 0 or 1
gR<p>	gR1	Read data direction of control pin (is input=0 or output=1)
gW<p><n>	gW10	Set data direction of control pin (input=0, output=1)

5. Sensor Calibration and Usage

The lancre firmware provides very generic tools for analog sensor read out and mapping that might be confusing at first look. This section will explain the ideas of this approach in more detail by providing an example for usage of lancre as a thermometer. I assume that a thermo measurement resistor is connected to ADC port 0 of the MCU board circuit. The described approach works for port 1 similarly and also for other sensor types that have a linear ADC to real value mapping.

In the calibration process you measure two pairs of value that establish a correspondence between the ADC digital value and the actual measurement. Each pair thus consists of (a,m) where a is the ADC value and m the mapped real value. In our example we want to calibrate a thermometer and thus use a real one to find the mapped real values. Since the lancre firmware only allows mapping to integer values you have to scale your real values. Here, we want to measure the temperature in centi-degrees Celcius.

Our first measurement is room temperature of 23 degrees or 230 centi-degrees. The corresponding ADC can be read out with the "a0" or "A" command or by pressing the orange key in link mode. My sensor read out is 0x175 (HEX) and now we can establish the first sample value pair. Since each value must be passed as HEX, 230 (centi degrees) results in 0xe6:

>cmwl0175,00e6

Make sure to write each value with 4 HEX digits.

Next, the upper sample value has to be provided. Here we measure a higher temperature. The higher the second value, the better the calibration will work. I chose to pick the second value by using the thermometer as a clinical thermometer. I measured a value of 0x18a for 37 degrees or 370 centi degrees. Again, conversion to HEX (370-> 0x172) allows to set the upper sample point:

>cmwu018a,0172

The two sample points are now specified and we can now launch the calibration process (for sensor at port 0) with:

>cmc0

The result of the calibration can be verified by having a look at the ranges for ADC and mapped values:

>cmr0a
=0022 03FF
>cmr0m
=0000 11D3

The values mean that the ADC measure range of [0x22,0x3ff] is mapped to the centi-temperature range of [0,0x11d3] or decimal [0,4563] (a maximum temperature of 456,3 degrees celsius. If you need negative values then you have to map the resulting values yourself and introduce an offset.

You can repeat the calibration by adjusting the lower and upper sample values and re-executing the calibration command cmc. Finally, you can store the found paramters to EEPROM:

>cS

Now the sensor is calibrated and you can access its values in mapped format. Use "m0" to measure a HEX value or "d0" to see the decimal value. For quick access the decimal value is also accessed by pressing the read key in link mode.

6. Have Fun!

Enjoy this project :) If you have questions, remarks or even ideas or patches for new commands or extensions then don't hesitate to drop me a mail. You can reach me as chris at my domain vogelgsang.org.