FAQ

About this FAQ

Shouldn't we divide this lengthy text into several pages?

No, all questions and answers are intentionally kept on a single page to make sure, that all keywords can be found easily without using a search engine.

How can I add to this FAQ?

If you are already registered on this wiki, go ahead. If not, you need to apply for registration by sending an email to nutwiki at egnite dot de. Due to massive and regular spamming, we decided to disable anonymous edits and automatic registration.

Something disappered. Did you remove parts from this page?

May be you are referring to the old NutOsFaq.

General Questions

What Is Ethernut?

Ethernut is the name of an Open Source Hardware and Software Project for building Embedded Ethernet Devices.The hardware part is a small board, also named Ethernut.

What are Nut/OS, Nut/Net?

Nut/OS is the name of the tiny real time operating system, which had been written to implement a TCP/IP stack. The TCP/IP part has been initially named Nut/Net.

However, as both are quite dependent on each other, nowadays the name Nut/OS is used for the whole software.

License

Can I copy Ethernut hardware and software for commercial products without paying royalties?

Yes. Schematics and board layout may be used in private or commercial products without paying any fee. Although many parts of the software had been taken from other projects, they can be used without paying royality fee and may be re-distributed in binary form with or without source code. But note, that you are not allowed to remove any copyright notices. You must present the copyright notice also in your documentation.

Is it published under an OSI certified license?

Not under a single license. But practically yes, almost all licenses are OSI certified.

Actually it is a bit more complicated. You need to spend some of your own time on this and possibly consult a lawyer, if you intend to use Nut/OS in a commercial project.

Can I use the Ethernut logo and product name for selling my own product?

You are welcome to copy the Ethernut design, but you can't sell it under that name, because Ethernut is a registered trademark of egnite GmbH. You need to choose a different name.

Is Nut/OS a registered trademark?

No, you can freely use it for your own product.

History

When did the project start?

Nut/OS had been started in 2001 as a fork of Liquorice.

How long will Nut/OS be supported?

If there is a significant decrease in downloads and active developers, Nut/OS may slowly die. Currently this is not the case. According to the SourceForge statistics at http://sourceforge.net/projects/ethernut/files/stats/timeline?dates=2010-01-01+to+2012-08-24 there are at least 400 download per month.

Host Environment

What do you mean with host?

Nut/OS applications are created on a PC, called host. The executables are then transfered to the so called target.

Which operating system are supported?

Mainly Linux and Windows. From time to time Mac OS X is tested with more or less success.

Is any emulator like Cygwin, Wine or Fink required?

No, all host tools are native executables, either build with autotools on Linux and OS X or distributed as binaries for Windows.

No serious professional development takes place on Linux or Mac OS X. Why not stop supporting these amateurs?

See next question.

No one is using Windows with Open Source tools for Embedded development. Why not stop supporting this ancient platform?

According to the SourceForge statistics, 80% of Nut/OS downloads are requested from Windows PCs. Thus, it is more likely, that Linux support will be terminated. Linux users may use Wine to run Windows executables.

Consequently, after a while, Nut/OS development will come to a halt, because the majority of developers are working on Linux and won't accept that decision.

Which exact compiler version is used to build Nut/OS?

When using GNU tools, building Nut/OS doesn't require a specific version, generally speaking. In reality, it happens sometimes, that Nut/OS fails to build when using a newer GNU toolchain. Mainly because GCC becomes more and more picky about minor flaws in our code. But Nut/OS is strict as well. When building the libraries, warnings are considered errors and compilation stops.

In any case, the current stable release of Nut/OS as well as the latest beta are regularly checked with the latest GNU toolchains. If it still fails, try an older toolchain.

What about ImageCraft compiler versions?

Support for compiler version 6 had been recently canceled. Version 7 is still supported, no later version have been tested.

Why do you nit-pickers consider compiler warnings as errors? This is very annoying.

We, the "nut-pickers society", want to force our developers (ourselves) to deliver highest possible code quality. Anyway, you can disable this by removing the -Werror option in nut/Makevars.*

Nut/OS developers will get punished, if they try this.

Are the GUI tools available on Linux and Windows? If yes, how is this done?

The graphical user interfaces, like the Nut/OS Configurator, are based on the cross platform GUI libraries wxWidgets or Qt.

You mean, you are using both, wxWidgets and Qt?

Not really, we are using either wxWidgets or Qt. Development began using wxWidgets on Windows. Ports to Linux or OS X didn't work as expected. After the development group grows, more developers were familiar with Qt and didn't feel comfortable with wxWidgets. One of them created his private Qt version first, which was later contributed to the project.

Unfortunately the Qt version still lacks certain features, which are available in the wxWidgets version. On the other hand, the wxWidgets version still doesn't work reliable on Linux and OS X. So both versions are still provided.

Are you crazy, spending time on two versions of the same tool?

Short answer: Yes, we are.

Long answer: It turned out, that most contributions are made by the initial developer of each version only. Depending on the preferences of the developer, it is often easier to fix an immediate problem in the wxWidgets version, than trying to add missing features in the Qt version, and vice versa. Most Qt promoters either disappeared or were just too busy.

See http://lists.egnite.de/pipermail/en-nut-discussion/2012-July/013703.html

Why are all header files collected in a single directory, apart from related C code?

Putting all header files into a single directory has the advantage, that only a single include path needs to be added to the compiler options, and still keep the pathname of all header files short.

Why not use symbolic links to solve this?

Symbolic links are well supported on Linux and OS X, but they are relatively new and rarely used on Windows. The developers are not sure, whether symbolic links may create unforeseen problems for Windows users.

Target Hardware

Which boards are supported?

The list at http://www.ethernut.de/en/hardware/boards.html is a bit outdated, but good for a first overview.

Can you recommend one of these boards?

It is not the intention of this FAQ, to direct you to a specific vendor. If you have a any application in mind, the mailing list may help to select one, that may fit.

Building Nut/OS Applications

Why does my existing application fails to build after upgrading Nut/OS?

Some configuration features may have changed. Therefore it is mandatory to create/update your sample/application directory.

My application still fails to build or crashes after upgrading Nut/OS. Do you have a list of changes?

Until Nut/OS version 4.8, changes were manually described in a file named Changelog, which is located in the top directory. Developers try to explain in a few words, what has been done, where it has been done, why it has been done and whether this may break existing applications. On the other hand, they committed code to the repository in a, well anarchistic way.

When switching from CVS to SVN, it has been decided, that code commits need to be clear, organized and accompanied by a description of the same quality, then it has been used in the Changelog file. This should make the extra work on the Changelog needless and maintaining this file was stopped.

That was the theory. Actually it took several months, until the quality of commits reached an acceptable level. Nevertheless, related modifications are often spread among several commits, which makes it difficult to get a full picture. During development of Nut/OS 5, the decision was made, to add short descriptions of changes to the NEWS file, which existed for some time without any relevant contents.

See http://lists.egnite.de/pipermail/en-nut-discussion/2012-August/013815.html

Why does my application fail after moving it from RAM to Flash?

There are several possibilities. One step is often overlooked. After changing certain configuration items, like the name of the linker script, you need to create/update your sample/application directory.

Does Nut/OS support floating point?

Yes, but it's not worth the hassle. It will significantly increase your code size and slow down your application. Most calculations can be done with integer values. Floating point number are required in very rare cases.

I do have a rare case. Do you support floating point or not?

Floating point support doesn't depend on Nut/OS, but on the compiler and the C runtime library.

Stop beating around the bush and answer a simple question: Do you support floating point or not?

Yes, but...

The details are a bit difficult. Partly the runtime library, specifically stdio, is provided by Nut/OS. If you really need to read or write floating point numbers, you must enable the floating point support of Nut/OS in the Configurator. To make this work, Nut/OS depends on the C function dtoa. Even if available, this function may introduce all kind of cross dependencies. For example, it tries to use the runtime library's malloc function, which conflicts with the one provided by Nut/OS.

Over the time this had to be fixed over and over again, because most runtime libraries either implement some internal equivalent, which they change without warning, or they implement the original code from the old Unix days, which, for whatever reason, requires malloc.

Try it. If it fails, try a different compiler version. If all fails, write your own dtoa and contribute it to Nut/OS. We will appreciate this very much. :-)

See also http://www.ethernut.de/en/documents/ntn-4_floats.html

Debugging Nut/OS

What is the purpose of the NUTDEBUG macro?

In early days, when Nut/OS was tiny and new and contained many undiscovered bugs, it often happened that it suddenly crashes after running fine for hours, days or weeks. Without any crash dump analysis available, it was almost impossible to determine, at what point the system failed. To help here, the preprocessor macro NUTDEBUG was implemented to enable system wide debugging output on the debug device, typically a UART. Dumping this output into a large file on the PC made it not only possible to determine the location of a late crash, but also to study the history.

After some time the system became stable and tracking this kind of bugs was rarely required. If the system failed after adding new extensions or modifying existing parts, it was quite likely to locate the problem in the new code and developers were no longer interested in the full debug output. As a result, the debug output was no longer maintained and became more and more incomplete, with questionable gain. Today, most developers prefer to add debug output locally, which is removed before committing the code.

I added local debug output to a module. Shall I keep it for the benefit of others?

No, you should remove your debug output lines before committing your code. In no case you should leave any debug output lines enabled. Not all application do open stdout or stderr and will crash at your debug output. Other applications may use that UART to control a robot, which may interpret your debug output as a command to kill the entire civilization. At least disable these lines either by a macro or convert them to C comment lines.

To make sure, that everything had been properly removed, you should also remove the stdio.h inclusion. Left overs are then detected by the compiler. Before you ask: Of course you need to keep this header included, when the original code needs it. (Funny question. Good you didn't asked that.)

Most likely the next developer will trace a different bug and needs to add other output lines, watching other variables, or tracing different parts of the code. Your debug output, which helped you to solve a problem, may now disturb more than it helps. It may even hide the new bug by adding additional delays or forcing the code optimizer to produce different code. Your initial attempt to be friendly may be considered unfriendly or rude by other developers.

Of course, there are cases, where debug output looks useful for everyone, like printing the return result of an essential function. Specifically when new functions are added, it makes sometimes sense to keep the debug output for a while. But as soon as the code is considered stable, it should be removed. All these ifdefs to include or exclude debug output make the code less readable and can become quite annoying.

Why not use variadic macros for debug output?

Simple answer: Because variadic macros are rarely supported by C89 compilers.

Complicated answer: Well, if you decide, that your debug output lines will never annoy others, because they are essential for all kind of bug tracing and therefore should be kept as part of the source code, then variadic macros look like a better solution than contaminating the code with preprocessor ifdefs and endifs. But keep in mind, that enabling your debug output is limited to compilers, which support this feature. In any case you must make sure, that your code still compiles on C89 compilers without warnings.

Nut/OS Device Drivers

What are device drivers used for in Nut/OS?

They mainly provide a common interface for C stdio support. Once a device driver is available for a specific hardware like a UART, an LCD or a keyboard, application can access this hardware with C standard functions like printf, scanf, fopen etc.

Do I need to write a device driver to access hardware?

Not at all. You can directly access your hardware like you would do without an underlying operating system.

Why does Nut/OS create separate code for each UART device?

As you may know, Nut/OS had been initially created for Atmel's 8-bit AVR family. This architecture allows to modify or test single bits in a single cycle, but only in the lower address range. UART hardware registers are located in this area and therefore it makes sense to use this feature to make the UART handling as fast as possible. However, the compiler can generate the proper code for single bit access only, if it knows, that the access will definitely take place in the lower memory area. For this reason, UART register addresses need to be constants. As a result, the UART driver has a very good performance. The back side of the coin is, that separate code is required for each device. As most AVR application are quite simple and require a single UART device only, this is no big deal anyway.

Now, keep in mind, that this works for UART0 and UART1 on AVR chips only. The real trouble is, that later drivers for extended UARTs and even other platforms had been created in the same way, although there is no benefit for them, just the disadvantage of duplicate code. In fact, all supported targets are currently suffering from this waste of program space, specifically larger chips, which may provide up to 8 UARTs. Due to the higher performance, these chips are attractive for applications, which want to handle more than just a single UART like the AVR boards.

Why doesn't Nut/OS, like the rest of the world, use C structures to define I/O registers?

The rest of the world, except Linux, right? Like Linux, Nut/OS mainly uses macro definitions to specify I/O register addresses. Instead of directly using a structure pointer, Nut/OS uses macros or inline functions like outr() or inr() to access them.

#define TX_REG 0x1000
#define RX_REG 0x1004
#define S_REG  0x1008

while (inr(S_REG) & 1);
outr(TX_REG, data);

Indeed, this is in contrast to most libraries provided by chip vendors, where C structures are used.

struct _ioregs {
 volatile uint32_t tx_reg;
 volatile uint32_t rx_reg;
 voaltile uint32_t s_reg;
};

struct _ioregs *regp = 0x1000;

while (regp->s_reg & 1);
regp->tx_reg = data;

This looks much nicer, doesn't it?

The problem with C structures is, that all memory accesses are subject to compiler optimizations. While the volatile attribute guarantees, that the access takes place in any case, it doesn't guarantee the sequence of accesses. One day you may recognize, that the compiler decided to move your first line, a device reset register access, towards to end of the register access sequence, spoiling all previous setting. As you can imagine, this are extremely hard to find issues. The only chance to avoid this is, to add so called fences to the code, which stops the compiler to shuffle your I/O access operations.

The advantage of using inline functions or macros is, that they can be implemented in a way, that fits to the compiler, without modifying the original code. Although rarely used, you may even add additional code to outr() and inr() to log, filter or emulate register accesses for testing purposes.

Doesn't the Nut/OS way of I/O access increase code size?

Yes and no.

Yes, because many drivers were crafted after the original AVR drivers, which require constants, as explained above for the UART driver.

No, because instead of passing a structure pointer you many pass a base address to re-use the code for several instance of the same device.

Using macros with inline functions or C structures for I/O register definitions doesn't influence code size.

Why are there so many different SPI drivers? I'm confused.

Initially, drivers either included their own SPI bus handling or used some generally available code, but leave it to the application programmer to take care of possible conflicts, when more than one device was attached to the bus.

Since Nut/OS 4.7.5 new API functions had been implemented to provide a framework for device drivers that control devices attached to this bus.

See http://www.ethernut.de/en/documents/ntn-6_spi.html

Porting Nut/OS to a New Target

Do you have a porting guideline?

http://www.ethernut.de/en/firmware/porting.html explains, how to port Nut/OS to an imaginary CPU named Zero. However, this CPU is just another ARM variant. We do not have any guide for other architectures. Nevertheless, this guide is quite useful, because it shows, which parts need to be touched to add a new CPU.

TCP/IP Stack

Is WLAN supported?

WLAN had been added as a demo many years ago, but hasn't been maintained since. Consider it broken.

The experience is, that WLAN hardware is typically short living PC hardware, replaced by newer chips within a few years, opposed to embedded hardware, which is expected to be available for a few decades.

Is PPP supported?

Yes, PPP is included. But be prepared, that it is rarely used and not well maintained.

Is IPv6 supported?

A few developers committed to implement IPv6 support at the new branch http://ethernut.svn.sourceforge.net/viewvc/ethernut/branches/devnut_inet6/

Actually development has come to a halt and the last sync with the trunk took place in April 2012.

Is SSL or TLS supported?

Transport layer security (formerly secure sockets layer) is under development on a related branch at http://ethernut.svn.sourceforge.net/viewvc/ethernut/branches/devnut_tls/

Which TCP protocols are supported?

The following TCP protocols are more or less complete: FTP (server only), HTTP (two versions, server only), SMTP (client only).

Which UDP protocols are supported?

The following UDP protocols are more or less complete: DHCP (client only), DNS (client only), SNMP (agent only), SNTP (client only), SYSLOG (client only), WINS (client only).

I need IP protocol XYZ. Are you going to support this?

It is not really our intention to add all kind of IP protocols. Some may be added over time, some may never appear. In many cases, it is quite easy to implement new protocols.

You may also look for existing code from other operating systems. The older, the better. In early times protocols had been implemented using pure stdio streams. Such old style source code perfectly fits and doesn't require much porting effort. You should always study the related RFCs.

Can I add other, non-IP protocols?

Yes, this is possible since Nut/OS version 4.8. A sample is provided at http://ethernut.svn.sourceforge.net/viewvc/ethernut/trunk/nut/app/pingnet/

Why does receiving data works but transmitting data doesn't?

Possibly the priority of your application thread is too high. Threads, which are using the TCP stack should run at priorities above 8. Note, that the lower the number, the higher the priority of the thread.

Contributing

Where can I find the latest development code?

The code repository is hosted at http://ethernut.svn.sourceforge.net/viewvc/ethernut/

Do I have to follow a specific coding style?

Yes, that's mandatory. Nut/OS uses K&R style, similar to the Linux kernel, but with subtle differences. More details are available at http://www.ethernut.de/en/documents/programming-style-guide.html.

Which C standard should I follow?

C89, period.

Well, with a few exceptions. For example, Nut/OS developers often use double slashes to mark temporarily excluded code or to keep some removed parts as a comment. While this is widely tolerated, it is still considered bad style.

You demand C89 while the whole world moved to C99?

In fact, the whole world is still moving towards C99. Some prominent examples, like the Microsoft C compiler, are supporting a minor subset of C99 only.

Beside some minor enhancements in readability, there is nothing missing in C89 and compilers will not create better code from C99 sources. Implementing the full C99 standard requires a lot of effort, and new compilers for new targets may not provide all features when published for the first time. The intention of Nut/OS is, to be available without requiring specific compiler features.

The whole world uses GCC for embedded projects. Wouldn't that make a good standard?

Your assumption is wrong. A large number of other compilers exist, which are partly incompatible with GCC. For example, GCC uses attributes while many others use pragmas. We try to keep Nut/OS available for as many compilers as possible.

Are you going to switch from SVN to git?

That's an ongoing discussion among developers. See

• http://lists.egnite.de/pipermail/en-nut-discussion/2011-December/013239.html
• http://lists.egnite.de/pipermail/en-nut-discussion/2012-August/013839.html

Support

Where can I get additional help?

Developers are regularly checking the [mailing list] and, if time allows, will be happy to help.

Why is my request in the mailing list ignored?

There are several possibilities. I'll try to sort them by likeliness.

1. Those, who know the answer, are too busy. It is sometimes helpful and accepted, if you repeat your request after a few days. But be careful. When repeating this too often, you may be completely ignored or removed from the list.
2. Your post is automatically rejected by the list processor, because it is too large. Do not send large logs unless you are requested to do so. Often HTML or rich text formatting significantly increases email size. Use plain text messages only.
3. Your request is complicated, difficult to understand or otherwise requires more time than the one, who may be able to answer, has currently available. Try to keep your request simple and clear. Do not send a list of questions, use a separate request for each of them unless they are very closely related.
4. Your question is not specific enough. "Nut/OS fails to compile" will not attract anybody to spend time on this issue. Try to be as specific as possible, e.g. which compiler, which version.
5. Your question gives the impression, that you want free help without effort. Spend some time to explain, what you've done yourself to solve your problem.
6. Your question doesn't need to be answered. "Who is using board XYZ?" may not be answered, because no one uses this board. You don't expect several hundred people answering "Not me", are you?
7. Those, who know the answer, may not see the questions, because you posted it as a reply to an unrelated thread instead of creating a new topic. If not interested in this topic, readers may unintentionally skip your request.
8. Those, who know the answer, may not see the questions, because you send a rich text or HTML formatted email, which their mail client is not able to display.
9. You are posting to the German mailing list, which is not regularly monitored.
10. The same question had been answered a few days ago or many, many times. Did you try Google?
11. Your question is not related to the Ethernut project and therefore annoying. You may still get an answer if you start the subject line with off topic.
12. Most unlikely: No one is able or willing to help.

Where can I subscribe or unsubscribe the list?

http://lists.egnite.de/mailman/listinfo/en-nut-discussion

Where can I get commercial support?

If you are willing to pay for professional support, contact one of the companies listed at http://www.ethernut.de/en/support/