small medium large xlarge

Back to: All Forums  Arduino
Generic-user-small
19 Mar 2012, 02:48
Lawrence Gill (9 posts)

I am new to Arduino and its programming language, so I am working my way through this book and learning things as I go. I have a question about the way the Arduino IDE displays the following code:

Telegraph::Telegraph(const int output_pin, const int dit_length) {
  _output_pin = output_pin;
  _dit_length = dit_length;
  _dah_length = dit_length * 3;
  pinMode(_output_pin, OUTPUT);
}

void Telegraph::output_code(const char* code) {
  for (int i = 0; i < strlen(code); i++) {
    if (code[i] == '.')
      dit();
    else
      dah();
  }
}

Here we see two instances of the word “Telegraph” followed by :: followed by a function name. In the lower instance, if I understand it correctly, the sketch is declaring the function named “output_code” which is in the class “Telegraph” using the void statement to indicate no data will be returned? And “void” gets colored orange in the Arduino IDE (version 0022).

In the upper instance I am thinking the function (or should I say “method”?)Telegraph of the class Telegraph is being declared. But the Arduino IDE colors this instance gray instead of orange. I am wondering what the gray color means, and whether or not I am correct in what I think those statements mean. The project works just fine for me, but I am trying to go along and place comments on most lines of all the code so I can gain a better understanding of what each line is doing in the whole sketch and the libraries it uses.

Thanks.

Maik_schmidt_avatar2_pragsmall
14 Mar 2011, 16:08
Maik Schmidt (122 posts)

Hi Lawrence!

Your interpretation of the code is absolutely right.

In C++ you specify a class member using a double colon, that is

void Telegraph::output_code(const char* code);

declares a method named output_code that belongs to the class Telegraph. Also output_code returns no value (void) and expects a character pointer (string).

To create a new instance (object) of a class in C++ you use a special function named constructor. A constructor has the same name as the class and does not return a value (not even void). So the statement

Telegraph::Telegraph(const int output_pin, const int dit_length);

declares a constructor that takes two integer arguments.

You can use it then as follows:

Telegraph my_telegraph_object(13, 200);

Regarding the colors: send_message() is colored orange, because it’s declared as a KEYWORD2 object in the file keywords.txt. I explain how keywords.txt works in section 4.7.

I totally understand that you’re confused. For example, output_code() is not colored orange. That’s because it is a private member of the class and should not be called from the outside. The dilemma for a library’s developer is that the syntax coloring should be a help for the users of the library and not for its developer.

Best,

Maik

Generic-user-small
14 Mar 2011, 20:32
Lawrence Gill (9 posts)

Hi Maik,

First I’d like to say that it is totally cool to be able to talk to the author of this book! Thanks for making yourself available this way. :)

I had some snags in the first parts of the book (mostly because I had not yet encountered this site, although in all fairness I think you did mention it up front. If so I had forgotten. The hardest ‘ice-breaker’ for me getting into the book (and Arduino code in general) has been that when I run across something not yet documented, and go to the Arduino forum for help, their is no clear path to a solution. I did not know until now that the code supported by Arduino was a rather specific subset of the much larger C++ language. So some forum members would suggest I read some tutorials on C++, and the first thing I encountered when doing that is code which the Adrduino IDE won’t support. I struggled along as best I could until finally encountering your explanation of “where all the code comes from” on page 74. It is finally coming together for me. That is why I posted the suggestion on the errata page that you might mention this earlier in your next revision of the book. I know it can seem overwhelming to a total beginner (having been there very recently!) but in my opinion it may have prevented the frustration I was having trying to figure out certain code words being used which do not appear in the Arduino IDE /Help /Resource section. During that time I did not know there were any alternative resources. Had it not been for a few very friendly folks on the Arduino forum I might have actually quit the whole project. I was close to that point of frustration.

So, thanks for clarifying the above, and for writing this book. Once I finish going through all the code and libraries used in this Telegraph project section, and adding comments to the code to help explain to myself what each line is doing, I shall happily press on forward. :)

One last question about the above. When I looked through some online material last night about Objects, Classes and Functions, it had said that creating a new object made use of the word “new”. In one post the writer even referred to the lack of the word “new” in a code segment and said it meant there were no new objects created in that segment of his tutorial. But I am thinking from your statement above that is one more thing different about the Arduino IDE? I don’t need to use “new” to create an object?

Regards,

Lawrence

Maik_schmidt_avatar2_pragsmall
14 Mar 2011, 21:57
Maik Schmidt (122 posts)

Hi Lawrence!

First I’d like to say that it is totally cool to be able to talk to the author of this book! Thanks for making yourself available this way. :)

You’re very welcome! For me getting feedback from readers is as much fun as writing the book!

The hardest ‘ice-breaker’ for me getting into the book (and Arduino code in general) has been that when I run across something not yet documented, and go to the Arduino forum for help, their is no clear path to a solution. I did not know until now that the code supported by Arduino was a rather specific subset of the much larger C++ language.

That seems to be a big problem for many people who work with the Arduino environment for the first time. I’ve tried to find a balance between very Arduinoish code and the pure C++ stuff. For me as a software developer it was very important to show that you’re able to run full-blown object-oriented C++ code on the Arduino.

During that time I did not know there were any alternative resources. Had it not been for a few very friendly folks on the Arduino forum I might have actually quit the whole project. I was close to that point of frustration.

Yes, the Arduino folks and the people on the forum are really great! I am happy to hear that you’re still on board!

One last question about the above. When I looked through some online material last night about Objects, Classes and Functions, it had said that creating a new object made use of the word “new”. In one post the writer even referred to the lack of the word “new” in a code segment and said it meant there were no new objects created in that segment of his tutorial. But I am thinking from your statement above that is one more thing different about the Arduino IDE? I don’t need to use “new” to create an object?

In languages such as C and C++ you typically create objects in two different memory areas: the stack or the heap. Objects on the stack are created automatically whenever you define a variable in your code. For example,

int i;

This creates a new int variable on the stack. For many purposes this is just fine, but one disadvantage of stack objects is that you have to know the size and amount of all objects you’re going to use in your program up-front. Programmers often say that you have to know “at compile time” what you are going to need.

If you need to create objects “at runtime”, then you have to create them on the heap. For example, you might read a configuration file that tells your program how many int variables you need. In C++ you’d allocate these int objects using the new keyword:

int *myints = new int[5];

This piece of code allocates five int variables and assigns a pointer to the first of them to the variable named myints. To access the first of your five int variables you’d use myints[0], to access the last one you’d use myints[4]. As soon as you no longer need them, you have to give them back using the delete keyword:

delete[] my_ints;

In principle that’s all you need to know about new and delete. There are many more aspects to pointers and dynamic memory management in C++ . Fortunately on the Arduino you do not have to care about them, because the Arduino C++ dialect does not support new and delete (I explain that in appendix B.1). But if you really need dynamic memory allocation someday on the Arduino, you can still use malloc and free. These are two C functions that are similar to new and delete.

Cheers, Maik

Generic-user-small
15 Mar 2011, 01:49
Lawrence Gill (9 posts)

Thanks for explaining that. One of the Arduino forum members just told me that in the line

@Telegraph::Telegraph(const int output_pin, const int dit_length); @

the function MUST be the same name as the class? Is this correct? I could not have the line

@Telegraph::Morse(const int output_pin, const int dit_length);@

instead if I wanted to use that name?

Regards,

Lawrence

Maik_schmidt_avatar2_pragsmall
15 Mar 2011, 06:50
Maik Schmidt (122 posts)

Hi Lawrence!

The forum member is right: a constructor’s name must be the same as the class name. Using a design pattern like named constructor you can overcome this limitation.

This pattern is usually used to define more readable names for constructors that differ only in their parameter lists.

Cheers, Maik

Generic-user-small
16 Mar 2011, 02:15
Lawrence Gill (9 posts)

Hi Maik,

I think I am finally gaining some understanding of Classes, Objects, Methods, and Functions. My original thought was that requiring the same name for the constructor (primary created object) and its class would limit the number of objects to each class. But I did some more reading on this subject and now realize that one can simply create secondary objects (any number of them?) as well as methods from each object, so there is virtually no limit to the number of eventual functions which can be made.

If I understand this now, it could work like this:

You can make a Class, such as Telegraph

In that Class you can use a constructor to make an object Telegraph (must be the same name as the Class)

Then, you can USE the Telegraph object as many times as you like by declaring methods of the object as many times as you like, using them in a format such as:

@Telegraph.code()@ @Telegraph.key()@ @Telegraph.device (3,2,1)@

You can also create more objects under the same class and Telegraph object by using statements such as:

@Telegraph one()@ @Telegraph two()@ @Telegraph three(3,2,1)@

And then use those (sub? secondary?) objects in the same format as above:

@one.code()@ @two.key()@ @three.device(3,2,1)@

Maik_schmidt_avatar2_pragsmall
16 Mar 2011, 20:09
Maik Schmidt (122 posts)

Hi Lawrence!

You’re absolutely right and welcome to the exciting and strange world of C++!

All the code samples in you last forum posting are correct.

There is only one more thing you have to learn: class methods.

In your posting you’ve used functions such as

Telegraph.code();
Telegraph.key();
Telegraph.device(3, 2, 1);

In C++ such functions are called class functions or static functions, because you invoke them on a class directly and not on an instance of the class. You have to call them as follows

Telegraph::code();
Telegraph::key();
Telegraph::device(3, 2, 1);

and this is how you’d declare them:

class Telegraph {
  public:
  static void code();
  static void key();
  static void device(int x, int y, int z);
};

Best, Maik

Generic-user-small
20 Mar 2011, 01:38
Lawrence Gill (9 posts)

Thanks, Maik.

I have been prone to confusing the two terms “function” and “method”. I haven’t quite figured out the real difference between them yet. If you could point me to the answer I would appreciate it. :)

I am on page 84, after having successfully figured out how to implement the piezo in the Morse Code Generator. When you said to replace the “output_symbol()” method with those 3 lines, it was not immediately clear to me that I needed to KEEP the remainder of the code which followed those lines and actually does the timing for the output pulses. When my result did not separate the individual tones for letters I did some troubleshooting and figured out what was lacking, put those lines back in, and got it to work.

I wonder if I may make a suggestion for future versions of this book? On page 84 you suggest adding an improvement to the library’s design such that it could support more than one output device. But in the code you used:

@Class OutputDevice { @ @ public: @ @ virtual void output_symbol(const int length); @ @ }; @

you used the word “virtual”. Once again I went to the Arduino Reference to look up a newly presented term and once again it has “no reference”. Perhaps for those of us with no C++ experience at all you could, in the very beginning of the book, put information on where and how to research Arduino IDE code terms which are not in the very shallow Reference section of the IDE. I have had to do a lot of online digging every time I encounter a new term like this, and often end up on some code page using things that work in some variant of C, but don’t work in Arduino. Once I learned many of these terms were defined in the library files that helped, but it isn’t made apparent to the beginner. I stumbled across that discovery quite far into the book, as I had mentioned earlier. What would be exceptionally ideal in your book would be a glossary of every code term used, with definitions, and for an outstanding experience, include simple examples which do not also include other as yet undefined terms. I am reminded of the book supplied with the TRS-80 Model I which taught how to program in Basic. Everything the new owner needed to know to learn how to program the TRS-80 was all in that single book. They stepped through all the code terms and used examples showing how they worked. I wish I had something like that for the Arduino. :)

I just did a Windows XP search of all files in my Arduino root folder on this PC(I have the typical library file extensions set to open with Wordpad), and found no mention of “virtual”. So in this sort of incidence, when you said “the rest is up to you” at the end of that suggested modification, I feel totally left out in the cold.

Regards,

Lawrence Gill

Maik_schmidt_avatar2_pragsmall
20 Mar 2011, 14:08
Maik Schmidt (122 posts)

Hi Lawrence!

I have been prone to confusing the two terms “function” and “method”. I haven’t quite figured out the real difference between them yet. If you could point me to the answer I would appreciate it. :)

Function is a generic term for a block of code that has a name. In object-oriented programming people often refer to functions defined for an instance of a class as method. So in practice it does not make a big difference.

Regarding the OutputDevice exercise: you’re absolutely right. For someone who has not experience in C++ programming (or object-oriented programming in general) this exercise is a bit difficult and in another edition of the book I’d add a complete C++ tutorial.

Despite all this I hope that you’ve learned a lot over the last week.

Best, Maik

Generic-user-small
20 Mar 2011, 16:08
Lawrence Gill (9 posts)

Hi Maik,

Yes, I have learned quite a bit, thank you! And your post above also taught me a bit more - that being, I am not missing certain concepts as I had feared. They simply have not yet been encountered. :)

I really do appreciate your taking the time to answer and help me sort things out. I have moved on to the next chapter now.

Have a great day!

Lawrence

You must be logged in to comment