some syntax not in arduino refernce guide?

Forum 2005-2010 (read only) Software Syntax & Programs
1

i was looking through the tutorial on interfacing arduino with a QT401 sensor. there are some commands and syntaxes that i totally don't understand and can't seem to find in the reference guide. is anyone able to explain to me what they mean?

the complete segment of code that i'm quoting from is included below if you want to see the context...

ok, first up:

byte qt401_transfer(byte data_out)

what does the bit in brackets refer to? i thought variable declaration just took the format type variableToDefine = value; - the example above looks to me like some kind of nested declaration or a function call...

second question:

while(0 < i) {

    mask = 0x01 << --i

hmmmm... i'm really stumped on this one. what do "<<" and "--" mean?

third question:

if(data_out & mask){

i couldn't find any reference to "&" as a logical operator in the reference guide... how does it work?

number four:

data_in |= mask

is this just an error and meant to be "!=" (ie, not equal to)...?

lastly, number five:

return data_in;

i can't find any reference to "return" as a command.... :frowning:

well, sorry these are probably such basic questions. but this bit of code looks like something that will be useful for a project i'm starting, so i'd love to actually be able to understand it properly...

is there a more extensive arduino 0007 reference guide somewhere?

thanks to anyone who can help me out!

jon.

(here's the snippet of code i'm referencing)

//
//  exchange a byte with the sensor
//

byte qt401_transfer(byte data_out)
{
  byte i = 8;

  byte mask = 0;
  byte data_in = 0;

  digitalWrite(qt401_ss,LOW); // select slave by lowering ss pin
  delayMicroseconds(75); //wait for 75 microseconds

  while(0 < i) {

    mask = 0x01 << --i; // generate bitmask for the appropriate bit MSB first

    // set out byte
    if(data_out & mask){ // choose bit

      digitalWrite(qt401_do,HIGH); // send 1

    }
    else{

      digitalWrite(qt401_do,LOW); // send 0

    }

    // lower clock pin, this tells the sensor to read the bit we just put out
    digitalWrite(qt401_clk,LOW); // tick

    // give the sensor time to read the data

    delayMicroseconds(75);

    // bring clock back up

    digitalWrite(qt401_clk,HIGH); // tock

    // give the sensor some time to think

    delayMicroseconds(20);

    // now read a bit coming from the sensor
    if(digitalRead(qt401_di)){

      data_in |= mask;

    }

    //  give the sensor some time to think

      delayMicroseconds(20);

  }

  delayMicroseconds(75); //  give the sensor some time to think
  digitalWrite(qt401_ss,HIGH); // do acquisition burst

  return data_in;
}
2

For now, see: Arduino Playground - BitMath

The reasons those operations aren't in the reference is because they seem like advanced features that we don't want to confuse people with. But it seems like we should reconsider. They could be added to the reference, or we could split the reference, as Processing has done, into regular and complete versions. Or maybe we could add some functions to replace some of those operations. We'll have to think about it.

3

The reasons those operations aren't in the reference is because they seem like advanced features that we don't want to confuse people with.

They definitely do confuse beginning users, but if they are explained (Like the link you provided does), everyone interested gets smarter. I'd like to see the reference guide become as thorough as possible, that way we can learn what we need to learn at our own pace (or when we come across examples with code we don't understand).

I'd be interested in helping design an indexed (possibly PDF) reference manual that could reside on a ebook reader or onscreen with the arduino environment. Thanks.

4

This will explain a lot of the mysterious operators you see in C++:

http://www.arduino.cc/playground/Code/BitMath

To answer some of the syntax questions that won't be explained there:

byte qt401_transfer(byte data_out)
{
    // ... code omitted ...
}

This is an example of a function declaration. The part inside parentheses is the list of parameters that are supposed to be passed to the function. It says, this function requires one parameter, of type "byte", and it is named "data_out". So you would call this function using something like:

    byte return_value = qt401_transfer(17);

This would send the byte value 17 as "data_out" inside the function qt401_transfer. As soon as the function returns, data_out no longer exists. It acts a lot like a local variable declared inside the function, only its value is passed in by the caller.

Whatever value is returned by the function (using the "return" statement) gets assigned into "return_value" in this example.

The operators like "--" and "++" are decrement and increment respectively. The "--" operator decreases a variable by 1, and "++" increases by 1.

If the "--" or "++" comes before the variable it modifies, the increment/decrement is performed before the value of the variable is used. This is called pre-increment/pre-decrement. If it occurs afterward, the value of the variable is used, and then it is incremented/decremented, and this is called post-increment/post-decrement.

For example:

    int x = 57;
    Serial.println (x);    // will display 57 on the serial monitor
    Serial.println (x++);  // also displays 57, because x is incremented after its value is accessed
    Serial.println (x);    // x is now 58, so that is what you will see
    Serial.println (++x);  // x is incremented before its value is used, so you will see 59.
5

Here is another example of using a function:

int sum_of_squares (int x, int y)
{
    return (x*x) + (y*y);
}

void setup()
{
    Serial.begin (9600);
}

void loop()
{
    Serial.println (sum_of_squares(3,4));
    delay(1000);
}

See if you can figure out what this code does. Then try running it on your board with the serial monitor watching to see if you are correct.

6

wow. thanks so much you guys. i think i totally understand now! and that bitmath page is AMAAAAZING! really useful.

as a total newcomer, i think i agree with mellis - having absolutely everything compiled into the reference guide may look daunting initaially, but in the long run it saves a lot of confusion. the processing reference is a good example of how newcomers can be introduced to the more basic concepts first, then have the opportunity of expanding on what they've learned. i've also been teaching myself max/msp, which at first seems hideously complicated, but if you work through the pdf tutorials in the documentation it's perfectly understandable, since the examples are so well explained - and if you ever want to find out about something a lot more advanced, the info is always easy to find.

anyhoo...

just one more question - can you put chunks of C++ code into an arduino program? is there any difference between the two? i've never seen C++ code, so i'm a bit confused as to why everyone is talking about C++ when i'm trying to learn arduino...

7

Your Arduino code is actually C++ and it's compiled by a C++ compiler. There are many parts of C++, however, that aren't supported by the compiler, so you can't just paste in anything you find in a C++ tutorial. Anything you find about plain C should work, though.