Documentation:NGW/TinyFirmware

From AVRFreaks Wiki

NOTE: This is a wikifization of an email sent by David Brownell to the avr32 kernel mailing list. The firmware package referred to can be found at http://niasdigital.com/bnizette/pmbus.shar.bz2

1 WHAT IS THIS?
2 WHY USE THIS?
3 SUMMARY INSTRUCTIONS
4 Building
5 Installing -- the hardware side
6 Installing -- the software side
7 Using the new firmware

[edit] WHAT IS THIS?

This is PMBus 1.1 [0] software intended to replace the firmware found in the "Board Controller" [1] on the Atmel ATNGW100 [2], which is a low cost ($US 90) Linux-oriented board suitable for developing and deploying AVR32 based embedded systems. This firmware can go into an ATtiny24 microcontroller which is found on that board, but which is not currently used for anything of note.

This is licensed under GNU GPLv3. The distribution files include

README -- what you're reading
COPYING -- copy of GPLv3
Makefile -- to build under Linux
pmbus_slave.elf -- pre-built binary
pmbus_peek.c -- userspace tool talking to the firmware

Plus of course the source code with the I2C/PMBus protocol code and microcontroller access:

main.c
pmbus.c
usi_i2c_slave.c
usi_i2c_slave.h
smbus_glue.h
prod_misc.h

[edit] WHY USE THIS?

There are several reasons this firmware may interest you:

Achieving what was originally promised for that chip. Despite documentation in the NGW100 board support package, the original firmware doesn't conform to any version of the PMBus spec. It won't return strings properly. Temperatures are encoded wrong. So is the board revision.

This firmware provides a basis for building the kind of board controller the NGW design envisions. Swap in a more capable chip (say, an ATtiny44), and it could do quite a lot.

As a Linux developer, you may not be familiar with AVR8 microcontrollers. This little project can be a gentle introduction.

Fortunately, one place the documentation is incorrect is where it says that the ATtiny can't be reprogrammed without taking it off the board. The "lock bits" have not actually been set, so it can be reprogrammed using standard AVR8 tools.

The USI controller which this firmware uses is available in all the ATtiny series chips plus larger ATmega{16,32,64}{5,9,50} chips, so it should be easy to make it work on other AVRs. (Retargetting to AVRs using TWI controllers for I2C shouldn't hurt much, either.)

[edit] SUMMARY INSTRUCTIONS

[edit] Building

This package is distributed with a pre-built firmware image, as well as the sources to build that image. So you don't *need* to build it yourself.

These sources build with gcc-avr; a simple Makefile is included, which you may need to tweak. On MS-Windows, use WinAVR-20071221 or newer; you may want to set up an AVR Studio project. On Linux, use a recent toolchain, but be careful of GCC 4.3.0 bugs.

[edit] Installing -- the hardware side

There are lots of ways to get firmware onto an AVR8 microcontroller; you can read about them in many places. I'll suggest using an AVR Dragon [3] programming adapter (USB connection, $US 50) connected to a six-pin ISP connector you solder onto your NGW100, but most any AVR programming tool will work.

As for soldering that ISP connector ... find the ATtiny24 chip on your NGW100, and notice the pair of 6-pin footprints on the board right next to it. The footprint at the head of the ATtiny is the ISP connector.

[edit] Installing -- the software side

Again, there are lots of choices.

One command line option is to use "avrdude", on both Linux and Windows. If you're using avrdude, you may first want to download backup copies of the EEPROM and flash data. Then erase everything and start from scratch.

AVR Studio also supports direct downloading (Windows only).

However, *DO NOT* try to do this using the debugger (DebugWire) unless you first remove the zero ohm resistor connecting the ATtiny24 reset line to the AVR32 reset line!! (It's labeled "0", and sits between the ATtiny24 and DataFlash chips.) DebugWire won't work, because of a capacitor on that line.

Newer toolchains should pick up fuse settings from the firmware image. The defaults are OK, except you should set EESAVE: once you set up the EEPROM, you probably won't want to do it again.

After you update the firmware, you should write two values into the EEPROM. That's easy with DebugWire and AVR Studio; just edit the memory display. You can also do it with ISP mode and avrdude.

Your board serial number, up to 10 ASCII characters starting at the beginning of the EEPROM. Copy it from the sticker on the bottom of your NGW board; it's not the product name or the manufacture date code, and may be like "NGW01234".

Two bytes of temperature calibration data, starting at the tenth byte. Start with the default offset, and update it based on the reported temperature. (Or leave it as all zeroes or all ones, to use a default and correct it later.)

[edit] Using the new firmware

You may have noticed that nothing actually tries to talk to the board controller, either from Linux or from U-Boot. Strictly speaking, the board's Ethernet addresses should be derived from its serial number, which should be retrievable from the ATtiny24 controller (according to its limited documentation). But there's no point in trying that with the original firmware.

You can use the enclosed "pmbus_peek" userspace client. It uses the /dev/i2c-N interface, and lets you examine PMBus devices such as this one. (Watch the original Atmel firmware misbehave! It uses address 0x0b; this firmware uses 0x35.)

[edit] FIRMWARE CAPABILITIES

This firmware uses the SMBus alert mechanism for asynchronous fault reporting. Unfortunately Linux doesn't yet support that mechanism, so if you care about faults you currently need to poll for them.

[edit] Sample readings:

Here's output from the firmware installed on one NGW board.

The hardware revision is shown in octal, and comes from two resistor ladders on the board. The serial number was copied by hand into the EEPROM. (The last digits could be used to generate Ethernet addresses for the board.)

Notice that there is one pending status alert, triggered by manufacturer-specific command #4. It can be cleared, possibly by code which notices the SMBALERT# signal.

This voltage might be a little bit high, but it's hard to say; only the first three of those digits are significant.

This temperature reading is with no chip-specific calibration. It's using the default offset (275) ... which is eighteen degrees too high. The EEPROM should be updated to record an offset of 275 - 18 = 257 = 0x0101, stored little endian into addresses 0x0a and 0x0b. (0x0123 would store as 0x23 into 0x0a, and 0x01 into 0x0b.)

       # pmbus_peek -s 0x35
       PMBus slave on /dev/i2c-0, address 0x35

       Inventory Data:
         Manufacturer:         Software Shak
         Model:                NGW100 PMBus
         Revision:             fw/0.7, hw/022
         Serial:               NGW01837

       PMBus revisions (0x21): part I, ver 1.1; part II, ver 1.1
       Capabilities (0x30):    SMBALERT#, 400 KHz

       Status 1000: mfr
         MFR_SPECIFIC          10: mfr_status_4

       Attribute Values:
         vout                  0349: 3.34593 Volts
         temperature_1         0028: 40 degrees Celsius

[edit] Supported operations:

Here's some output showing the device identification data and the results of QUERYing all PMBus 1.1 commands to see what this firmware supports.

       # pmbus_peek -l 0x35
       PMBus slave on /dev/i2c-0, address 0x35

       Inventory Data:
         Manufacturer:         Software Shak
         Model:                NGW100 PMBus
         Revision:             fw/0.7, hw/022
         Serial:               NGW01837

       PMBus revisions (0x21): part I, ver 1.1; part II, ver 1.1
       Capabilities (0x30):    SMBALERT#, 400 KHz

       Supported Commands:
         03 clear_fault                w nodata
         19 capability                r  u8 (bitmask)
         1a query                     r  process_call
         30 coefficients              r  process_call
         78 status_byte               r  u8 (bitmask)
         79 status_word               r  u16 (bitmask)
         7e status_cml                r  u8 (bitmask)
         80 status_mfr_specific       r  u8 (bitmask)
         8b read_vout                 r  s16 (DIRECT), Volts
            Coefficients: READ b=0 m=25135 R=-2
         8d read_temperature_1        r  s16 (LINEAR), degrees Celsius
         98 pmbus_revision            r  u8 (bitmask)
         99 mfr_id                    r  block, ISO 8859/1 string
         9a mfr_model                 r  block, ISO 8859/1 string
         9b mfr_revision              r  block, ISO 8859/1 string
         9e mfr_serial                r  block, ISO 8859/1 string
         d4 mfr_specific_04            w (UNKNOWN call syntax)
         d5 mfr_specific_05            w (UNKNOWN call syntax)
       #

       Those two manufacturer-specific commands are for testing.
       They trigger manufacturer-specific alerts, and raise an
       SMBALERT# IRQ for the host to handle.