Picture of AVRSH: A Command Interpreter Shell for Arduino/AVR.
Ever wanted to be "logged in" to your AVR microcontroller? Ever thought it would be cool to "cat" a register to see its contents? Have you always wanted a way to power up and power down individual peripheral sub-systems of your AVR or Arduino in *real time* ? Me, too, so I wrote the AVR Shell, a UNIX-like shell.

It's UNIX-like because it's reminiscent of the shell account you went out and bought to run your irc nick collision bots on, as well as having a command or two in common. It also has a filesystem that resembles UNIX extfs, using an external EEPROM, but that's become a project unto itself so I'll be releasing that module separately under a different instructable when it's production-ready.

Here's a list of the things you can currently do with the AVR Shell:
  • Read all your Data Direction Registers (DDRn), ports, and pins in real-time
  • Write to all your DDRn's, ports, and pins to turn on motors, LED's, or read sensors in real-time
  • List all known registers on the system
  • Create and store values in user-defined variables backed up by EEPROM.
  • Create a root password and authenticate against it (used for telnet access)
  • Read the configured CPU clock speed
  • Change your CPU clock speed by setting a prescaler
  • Start and stop 16-bit timers for timing of various things
  • Power up and/or power down peripheral sub-systems: Analog to Digital Converters (ADC), Serial Peripheral Interface (SPI), Two-wire Interface (TWI/I2C), UART/USART. Useful for when you want to reduce power consumption of the microcontroller or to enable certain functions.
  • Written in C++ with reusable objects.

This instructable will walk through the installation, use, and customization of avrsh.
BillylegotaI5 months ago

This is very inspiring. I am working on an ATmega1284 based microcomputer and your code has given me some valuable insights on how to create a CLI (I mainly do HW not SW so this is very helpful).

nevdull (author)  BillylegotaI1 month ago

Heyas, thanks for the kind words. I'm like your project you mention. I have a similar one, myself. If you have gotten some work done on it or want to discuss more technical aspects of persistent microkernels on MCUs drop me an email.


Anrax3 years ago
little issue here not sure if its me or just the regular look in c but it wont compile at all in avr studio 5 .. been siting an working away the errors buts an very long list of them .....

so question is what compiler was used and what platform of c as it really don't want to be nice to me ..
nevdull (author)  Anrax3 years ago
Sorry to hear you're having so many problems with the compile. To be honest, I haven't tried compiling it under AVR Studio 5 yet. I believe I used either WinAVR or avr-libc and the avr (gcc 4.5.2) package under Linux.

If I get some free time I'll try converting the package over to AVR Studio 5 and post a zip file.

Good luck!
fravashyo nevdull10 months ago


I tried to compile avrsh on linux (using avr-libc and avr-gcc-4.8.2) but all I get is:

In file included from common.h:15:0,
from common.cpp:8:
common.h:114:27: error: variable ‘PortPins’ must be const in order to be put into read-only section by means of ‘__attribute__((progmem))’
extern PortPin PortPins[] PROGMEM;
make: *** [obj/common.o] Erreur 1

Do you have some idea?

Anrax nevdull3 years ago
nice :)

hopefully i will learn from it
pitachip2 years ago
Wow I am so excited to use this. Seriously thank you so much for making this, nevdull!

I had no problem uploading to my Atmega328p and even connecting to it with CoolTerm (Mac OS) since I can see the 'root@Atmega328p' command prompt. But I'm having problems sending messages. I get things like the following:

root@ATmega328p> print registers
<> p....reVk..rs.: unknown command.

Anyone using CoolTerm and having the same problem? I'm assuming there's some setting within CoolTerm that may fix it?
Ok just in case anyone is using CoolTerm to connect, make sure of the following under 'Options':

(1) Make sure 'Line Mode' is selected under 'Terminal'
(2) Make sure 'Use transmit character delay' is selected under 'Transmit Options' with its default delay of 3ms
nevdull (author)  pitachip2 years ago
Do you have the ability to simply launch 'telnet' from the command line on your mac? That might be another alternative.

nevdull (author)  pitachip2 years ago

Hey, I'm glad you liked my project and instructable. As for your problem, I had many of the same type of errors but the two main culprits always were either:

1. The telnet client is sending telnet packets/commands and the AVR shell doesn't know how to interpret them. I'm just riding on port 23 TCP but don't implement any of the telnet protocol. I've found TerraTerm and a couple other windows telnet clients did this. I wrote my own which I've linked in the project elsewhere.
2. There is a baud-rate mismatch. If you have your baud rate based on your FCPU MHz set very far outside of the specs for the AVR shell, they won't sync up and all you'll get is garbage.

So, depends whether you're constantly getting garbage (problem 1) or just getting garbage upon connection (problem 2).

Hope you manage to figure out the issue and have some fun with the shell. For a full-throttle, extreme version of this, check out the MUNIX project which endeavors to build a viable UNIX-like workstation using nothing but 8-bit AVRs and linear/logic chips. From the keyboard controller (ATtiny45) to the USB host controller (ATmega32U) to the main dual processors (ATxmega256A3), this workstation has all the code for filesystems, unix-like shells, process control, memory management, linking and loading. More at http://www.munixos.net

Have fun and thanks for the comment!
doctorwho84 years ago
This is truly amazing. But one question comes to mind. How'd I go about sending the resulting HEX file to the Arduino? Does it use one of the tools that're otherwise popular for the hardware platform?
rasyoung4 years ago
nevdull (author)  rasyoung4 years ago
rf_4 years ago
Thanks for sharing your project!

I like it, max Kudos!

Spydamonky5 years ago
 Can you view the code on the avr? thats what im looking for...
mathman475 years ago
Nice job.  How long did it take to write this (the code, not the Instructable)?  Maybe someday I'll know enough to use this!
nevdull (author)  mathman475 years ago
thanks mathman,
I wrote the shell over the course of a weekend, and the windows terminal in about  a week.  It took longer for the terminal than I expected because I was doing research-oriented development and added a TCP/IP server to it so it could proxy telnet to my AVR and Arduino.  I have a half-written "Telnet to your Arduino" instructable that I just never had the heart to finish. haha.

The shell is somewhat naive, being a first-pass stand-alone shell.  I have a much more robust command interpreter that's being released with the μnix workstation and μnix Operating System when it gets to some level of usability.
nevdull (author)  nevdull5 years ago
Project at μnix Launchpad, if you're really bored.
Leesam5 years ago
Would pins 2 and 3 be used for RX and TX for this? I loaded the .hex on my Atmega168 (Avrdude verified it after and looked ok) and setup a Bus Pirate V3 as:
Uart 9600
no parity
1 stop bit 
Receive polarity idle 0
Output type normal (high=3.3volts, low=ground)

I was trying to use it as a Uart bridge which makes the bus pirate act as a regular RS232 usb adapter. When i connect i get nothing but 0xFF over and over.

Any ideas?
nevdull (author)  Leesam5 years ago
See my reply below, as well, but I think this version of avrsh was compiled at 57600 baud.
Leesam Leesam5 years ago
I think i saw F_CPU defined as 16Mhz in one of the source files. I just remembered that my Atmega168 was fresh and not set to use the 16Mhz crystal yet...

That's probably whats messing with mine, i'll fix it and post reply if everything works out.
nevdull (author)  Leesam5 years ago
Yah, if it's a fresh ATmega168 then I believe it defaults to the internal 8MHz RC oscillator with the CKDIV8 fuse enabled, making fcpu  effectively 1 MHz..  As for the pins, it's PIND0 and PIND1 for RX and TX which are pins 2 and 3 of the chip itself (ie the 2nd and 3rd pins from the top on the left where pin 1 is marked).

Good luck!
dude, I love this one ... really really nice, we like!
nevdull (author)  dcuartielles5 years ago
We thankses yous!
zingberra5 years ago
I guess you have seen bitlash? http://bitlash.net
nevdull (author)  zingberra5 years ago
That's an interesting project, but looks tied to Arduino libraries?
trialex5 years ago
Congrats - this is not only a unique and powerful project, but also one of the best written Instructables. Kudos.
nevdull (author)  trialex5 years ago
Thanks trialex and Xiver. I appreciate the kind words. I'm slowly rolling a UNIX-like operating system together to run on 8-bit AVR's. Finishing up the filesystem now, and have been testing the telnet interface. It's pretty cool being able to telnet from school and login to my AVR at home. lol. maybe that's going too far. ;) Cheers!
Xiver5 years ago
Excellent. Thanks for taking the time to toss it out to us.
jlafay5 years ago
Thank you thank you thank you!! This is going to be great for debugging my arduino projects. Many more thanks to you nevdull.
nevdull (author)  jlafay5 years ago
Thanks a lot! I hope it integrates well with your projects!
Origin5 years ago
This is amazing! What a great way to poke around at the more low-level stuff of the AVR, without sitting through a write/upload/run loop. I can't wait to try this!
nevdull (author)  Origin5 years ago
Thanks! I hope you like it!