So you want to create an MRBus node. The easiest way to start is based on one of the template projects - basically an easy outline that can be copied and critical sections filled in to make a fully functional component.

Step 0 - Get the Toolchain

You'll need some sort of gcc-based AVR toolchain in order to build the projects. If you're already doing AVR development, chances are you'll already have these things set up.

Under Debian-based Linux distros (Debian, Ubuntu, Mint, etc.), you'll typically need packages gcc-avr, avr-libc, and avrdude.

With Windows, it should be possible to build things using the popular but dated WinAVR package or a more updated version, like MHV AVR Tools.

Step 1 - Get the Template Project

At the moment, there's only an AVR template project. If there's ever future demand, a PIC version could be created.

The AVR template project can be found in subversion here: SVN?: svn://mrbus.org/mrbus/trunk/mrb-avrtemplate

Tip: You're probably really not going to want all the subversion? stuff in your mrb-avrtemplate directory. After all, you're going to change this into a new project, and probably put it under a new name and your own version control. So you're probably going to want to use "svn export svn://mrbus.org/mrbus/trunk/mrb-avrtemplate" to get the latest copy.

This will create a directory structure that consists of the following:

mrb-avrtemplate/
 src/
 src/Makefile
 src/mrb-avrtemplate.c

Step 2 - Get the MRBus Core Library

Of course you'll also need a copy of the core library. The best place to get this is again from our subversion? archive. If you already have this, then don't worry about step 2.

SVN?: svn://mrbus.org/mrbus/trunk/mrbus

Put that at the same level as your mrb-avrtemplate directory, so you'll now have something like:

mrbus/
  src/
  src/mrbus.h
  src/mrbus-crc.c
  src/mrbus-avr.c
  src/mrbus-avr.h
  src/mrbus-pic.c
  src/mrbus-pic.h
mrb-avrtemplate/
  src/
  src/Makefile
  src/mrb-avrtemplate.c

Go into your mrb-avrtemplate directory and type "make hex". If it all passes and creates a mrb-avrtemplate.hex file, you're good to go.

Step 3 - Rename Your Project

Well, come on, you're not making a new template, you're making a real node. So to thoroughly rename your project:

1. Rename your mrb-avrtemplate directory
2. Rename the mrb-avrtemplate.c file to the same base name as you gave the directory
3. Change the header on your application C file to reflect its new author and new name
4. Change the BASE_NAME variable in the Makefile to your new base name
5. Change the header on your Makefile file to reflect its new author and new name
6. Run "make hex" again just to verify it all still works, and fix any problems.

Step 4 - Set up Your Hardware

The actual construction of basic MRBus hardware with an AVR core is pretty simple.

At a bare minimum, you need:

• A supported AVR (basically any atTiny or atMega with a U(S)ART).
• An RS485 bus driver. Any standard pinout 8-pin half-duplex RS485 driver with a low unit load (preferably 1/8 unit load or less) will do fine. Recommended parts would be ICs like the Linear LTC1487 or Exar/Sipex . Lots of manufacturers make decent 485 drivers that will do the job.
• A clock crystal and associated capacitors (we recommend 20MHz, used with 20MHz rated AVRs)
• A voltage regulator or 5V supply. MRBus runs at 9-15VDC on the bus power lines. If you're taking power off the bus, you'll need to regulate that down to +5V, +/-5% to keep the AVR and RS485 driver happy. If you just want to use a 5V bench supply during development and you've got a common ground with the rest of your bus, you're fine as well.
• An AVR programmer, connected properly to the AVR's ICSP pins. If you don't have one, my programmer of choice is Adafruit Industries' USBtinyISP.
• If your node isn't going to be connected into a bus, you'll need to provide the bus bias resistors? in order to give the RS485 lines the correct idle state.

(Fixme: insert basic 485 / AVR connection schematic here.)

Once you get your shiny new AVR on your breadboard and wired up, you'll need to adjust the Makefile to match your hardware target. Things to change:

• DEVICE - The target AVRdevice for your node
• F_CPU - The target device clock speed, in Hz. We usually just go for the full 20MHz based off an external crystal, and haven't really tried other frequencies. They *should* work, but we have no idea if they actually do.
• FUSE_L, FUSE_H, and FUSE_E - The configuration fuse bytes.B e very careful with the fuse values - the wrong values could brick your AVR (at least unless you have a high voltage programmer). To calculate fuse values, I highly recommend the Engbedded Fuse Calculator.
• AVRDUDE - The command line for invoking avrdude. Usually all you need to change here is the target programmer type (the -c option).

Step 5 - Write Your Node Application

As it is, the mrb-avrtemplate project should be able to respond to pings? and eeprom read? and write? requests.

(The example template reads its MRBus address from EEPROM address 1, so don't forget to program it with something sane.)

At the very least, visit all of the sections in the code with a FIXME comment - these are generally the parts of the template people add things to.

Tip: The MRBus Core Library Reference documents the defined behaviour of MRBus library functions and variables. Basically anything with "mrbus" in the name gets described here.

That said, the most obvious question is "What the heck does this stuff do?" The easiest way to understand it is probably to walk through how the template project was built.