Friday, March 16, 2012

How to Setup and run Ritchieduino

Hi again. The reason of this post is to show how to successfully set up the a developing environment to use Ritchieduino library. I will also assume some form of Arduino board available, running in Windows, even though any other platform will have just some adjustments. If you use for instance the ICSP mode you are on you own regarding avrdude.

To set up the environment the following software packages are required:
  • Ritchieduino package needed files which are here.
  • The latest winAVR, this is important because it provides the tools and configuration of the AVR-GCC tool chain. Don't forget to allow winAVR setup to change the your PATH variable so that the AVR eclipse can find it automatically. Please note that there may be a bug in which the setup destroys your pre-existing path. If such thing happens please go to the directory in which winAVR is installed and look for a file named path1.log which contains your previous PATH variable so that you can fix it.
  • The latest Classical Eclipse IDE, to use as the development environment. Before downloading it is necessary to check whether the Java virtual machine is 32 or 64 bits. To do that just make sure  Java is installed typing java -version. If the command successfully runs and there is not any mention of 64 bit in the output than it is a standard 32 bit Java Virtual Machine and you should download the 32-bit version of Eclipse. If the command fails it is possible you don't have java installed and you must install it from here. It is advisable to have the 32 bit Virtual Machine or there may be problems with RXTX plugin for Eclipse that allows the Serial console functionality

The following steps should be taken in order to make sure everything is set up correctly. The steps which are probably optional will be detailed for sake of completeness. More experimented users will probably be able to skip some steps.

  1. (Optional) This first step is to install the Arduino Windows drivers for the first time, so most users will probably be able to step over this. It is also really simple. The Arduino board should be connected to the USB port and  the"Windows key+r" be pressed at the same time. On the Run dialog write "devmgmt.msc. On the device manager window try to find "Ports (COM & LPT)". Under that is "Arduino UNO (COMxx)", where xx denotes any assigned port number (normally COM7). Right clicking and selecting "Update Driver Software" should open a dialog. Select "Browse my computer for driver software", the appropriate location for the Ritchieduino package should be selected. The drivers are in "\drivers\.inf". Hopefully the driver is successfully installed and the next steps can be taken.
  2. (Optional) The installation of winAVR is pretty much straight forward just keep in mind the problem with the PATH variable mentioned above.
  3. (Optional) The most critical and time consuming task is to install and configure the Eclipse IDE with everything a programmer needs to be productive.The first thing to be done after downloading Eclipse IDE is to extract it to somewhere. After that, it open it for the first time.
  4. (Optional) Upon starting Eclipse for the first time a directory should be selected where the projects will stay. Eclipse calls this directory workspace. It is advisable to either leave the default directory set or create one specifically for this purpose, so that everything stays organized in one place without future conflicts, like with Git. The check box  "Use this as the default and do not ask again" should also be activated so that any accidental change doesn't break the set up. Upon proceeding you will be officially inside the Eclipse IDE and will be greeted by a "Welcome to Eclipse" screen. Congratulations!
  5. (Optional)  In this step necessary plugins will be installed in Eclipse, specifically the CDT, AVR, EGit, RXTX and Target Management Terminal.
    1. So on the menu bar select "Help->Install New Software". When the new dialog appears, click on "Add" which will open a dialog to add a repository. In this case, the repository to add is the AVR plugin. The name can be anything, but for the sake of completeness it will be named "Avr Eclipse Repository". The location will be "". Note that this address can change, although unlikely.
    2. On the combo list "Work with:" the "Avr Eclipse Repository" should be selected. It is likely that a "Pending" will appear on the list below. It can be a while, as Eclipse is fetching the available plugins. 
    3. Afterwards the "AVR Eclipse Plugin" should show on the list and its check box should be activated. 
    4. Pressing "Next" twice and followed by accepting the license should highlight "Finish" which should be pressed to start the plugin installation process. 
    5. You should wait while software installs. During the installation it is possible that Eclipse warns you of unsigned content and you should continue the process. If you need re-assurance follow to the original AVR plugin site and check that the address supplied before matches the recommended in the site.
    6. Upon request restart Eclipse IDE.
    7. The process of installing another plugin will be repeated now for CDT, the component that adds general C/C++ functionality to the IDE.
    8. Following the Help->Install New Software" receipt again, select on the combo list "Work with:" the "All Available Sites".
    9. Below the combo box should be an empty text box which acts as a filter. There the text "C/C++ Development Tools" should be pasted. Note that if you manually write it, Eclipse IDE may hang because it is filtering the whole plugin list aggressively character by character. Even so it might hang some time.
    10. Tick only the "C/C++ Development Tools" and proceed like in the AVR plugin installation (step 5.5). In the end of this step it would already be possible to target AVR hardware but regarding Ritchieduino some more steps are required.
    11. Again the process will be repeated, only now to install eGit which enables the cloning of the Ritchieduino repository in Github.
    12. To install EGit the instructions are similar to the ones in step 8 just that this time the filter should be "Eclipse EGit" proceeding with similar previous steps to install it.
    13. Similar to the procedure in Step 5.1 followed to add the AVR plugin, RXTX repository is required to be added. To do so add "" selecting afterwards RXTX 2.1-7r4 and installing it. 
    14. This time the procedure is similar to the installation of EGit, just write in the filter "Target Management Terminal" and proceed with the install.
    15. The plugins installations are complete and it is time to start cloning the repositories
  6. In this section the Ritchieduino clone will be done.
    1. It is possible to clone the Ritchieduino repository by following "File->Import->Git->Projects from Git->Next" and then a dialog will ask you to select the repository. For that click "Clone"  and a dialog with lots of text boxes will appear. 
    2. Fortunately only the URI one is needed and in it input "git://" and all other fields will automatically be set. Clicking "Next" will connect to the repository and Master branch will be already pre set. Continue with "Next" and "Finish" the repository will be set up. The dialog will close.
    3. If the repository was successfully added, the Ritchieduino repository should now be selected proceeded with "Next".
    4. Check that the "Import existing projects" radio button is set and just press "Next", and "Finish" in the next page.
    5. If everything has gone well the Ritchieduino default Projects should have been imported, making one more step complete.
  7. In the following steps the AVR environment will be configured according to the required AVR target chip.
    1. Starting by going to to the menu bar "Window->Preferences".
    2. In the opened dialog collapse the "AVR" tree-list and select "Paths".
    3. If the winAVR installation was successful all the paths should be already pre-set, with the exception of the Atmel Part Description Files. In the list find "AVRDude" and click on "Edit".
    4. On the "Change Path for AVRDude" change the "Path Source" to "Custom". Afterwards select "Browse...". Selecting the Ritchieduino Software Package folder that was previously downloaded is all that is necessary. 
    5. Back in "Preferences", now looking again at the tree list, and under "AVR", select "AVRDude".
    6. Mark  "Use custom configuration file for AVRDude" and "Browse", selecting again the Ritchieduino Software Package folder.
    7. Now on the "Programmer configurations" press "Add..." .
    8. A big dialog should open, and in the "Configuration Name" Ritchieduino should be written.
    9. The "Description" can be anything.
    10. On the "Programmer Hardware" list, "Arduino" should be selected.
    11. The "Override default port (-P)" text box should be set with \\.\COM7. (Without the dot).As mentioned earlier it can be other COM number, but normally its 7.
    12. The "Override default baudrate (-b)" should be 115200.
    13. Proceed with "Ok" until the "Preferences" dialog closes.
  8. Now there is a quite boring task that has to be repeated for all the libraries that you are going to use in Ritchieduino, but in fact is crucial and can't be defaulted, which is setting the target chip. For the sake of simplicity only the steps for RitchieduinoCore.
    1. On the menu bar go to "Window->Show View->Project Explorer"
    2. On the Project Explorer left click on the RitchieduinoCore project and select "Properties".
    3.  On the tree list select "AVR->Target Hardware".
    4. On the "MCU Type" you should select your target chip and in the "MCU Clock Frequency" the frequency. For instance for the Arduino Uno, the type is "ATmega328p" and the frequency "16000000".
    5. This whole step should be repeated for every library you wish to use once and every new project you decide to create. If this step is not taken your applications may not work correctly.
  9. There is a project ready to try which is the RitchieServer, an example ready to run. It is important that step8 is done on this project also. Note that the Ethernet shield is necessary.
    1. Go to the menu bar and select "Window->Open Perspective->Other". On the dialog that appears select "C/C++".
    2. On the Project Explorers' tree list collapse and double click "RitchieServer->main.c" so as to see what is being executed.
    3. Care should be taken so that the network settings in the source file match the desired local network.
    4. To build this project you only need to go to the Project Explorer, right click RitchieServer and select "Build Project".
    5. It will take some time in the first run but should be relatively fast afterwards (faster than the Arduino IDE).
    6. Upon reading "**** Build Finished ****" on the console vie.
    7. If everything has been successful it is now possible to upload to the board.
    8. To upload the program just select the RitchieServer project in Project Explorer and click on a green AVR icon on the tool bar in the upper part of the Eclipse window. Alternatively it is possible to do "Ctlr+Alt+U"
    9. After the upload to see the results of the Serial port data doing "Window->Show View->Terminal" is needed.
    10. After the terminal shows in the tabs in the view sub window there is a small button called "Settings".
    11. In the dialog that pops up the "Connection Type:" should be set to "Serial" and the "Port" should be set to COM7 or if different to the relevant one. The baud rate should be noted in future uses. Pressing "Ok" closes the dialog.
    12. Pressing the small green "Connect Button" connects to the serial device.
  10. If everything has been successfully executed the terminal should now be printing, for the case of RitchieServer, "Comunications Initted".
That is all that is needed to set up Ritchieduino. There will be another post on how to make a Hello World be printed in the Serial output.

Wednesday, March 14, 2012

Ritchieduino, What it is and why

Hello, this is my first post about the library i have created exclusively in C99 for the Arduino board, even though it might work with other AVR chips also and outside the Arduino board. I had already made a post on Arduino Forums, where a brief explanation can be found.
The Ritchieduino comprises much of the Arduino-0022 library functionality (pin compatibility), just completely written in C99 (not K&R C) and with some re-arrangement to make the code more modular. Also all the C++ code was mostly stripped off and the more important parts were partially re-written, namely the Serial, the SPI and Ethernet (w5100) libraries. Because of this re-writing the API changed significantly and i admit it is aimed at a more savvy audience than the original Arduino.

On the other hand as the including headers have been streamlined and the namespace cleaned some room for extra optimization control was gained. A clearer example is that mostly only the wiring library remained, which was already C. There were also some functions which were, in my opinion superfluous, that were cleaned out, namely re-naming of standard C functions, like the ones in WCharacter.h and WMath.h. I do reckon renaming is mostly inlined and doesn't bloat the code by itself but makes the analysis and deeper understanding of what is going on behind scenes mores obscure.

Still on the line of modularilization is the fact that in my opinion, Class Inheritance has been abused as to make Matroska doll code, where you have to go deeper and deeper to inspect what is happening under the hood, becoming even harder for newbies to start progressing to Intermediate level. An example of this is the print inheritance on pretty much every class, which sometimes calls code that is less than desirable, namely floating point code, which increases the size of the programs by some orders of magnitude.

As a final personal note i would like to notice that in no way i am diminishing C++, on the contrary. I think it is a much more powerful language with some concepts that, if not well understood and disciplined, can lead to quite obfuscated code. That and the fact that there doesn't seem to be any discipline regarding coding style as simple as a variable naming convention. A good example is in the socket.c file, where the socket descriptor variable can be called s, _s, sock or socket. The convention followed by Ritchieduino and its libraries attempts to follow as closely the Google Coding Style Guide as possible, even though there are exceptions(not the C++ ones) in the name of compatibility with the original Arduino library. I also advise a look into the guide even if you are not interested in Ritchieduino because for me it was really useful. It is even for C++!

There will be more posts on how to start and use the libraries, as it doesn't use the Arduino IDE, which in my opinion is terrible. I will make a post on how to set everything up in Eclipse IDE with some hints that may help the transition to Ritchieduino and even normal Arduino programming a bit faster and satisfying. In the meantime if you can take care of using the library you can try the WebServer examples which is functionally equal to the one provided in the original Ethernet library.

In the meantime i leave here the github repository with library available to anyone who so desires. It is also important to note that the library is LGPL, because the previous Arduino work upon which Ritchieduino is derived, is also LGPL, so you can use it in proprietary applications.

Hope enjoy it.
Paulo Neves