Tips: How to ask for help

Please put some money in the tip jar by clicking on the donate button to support me so I can continue creating contend like this. P.S. please donate more than $1 as PayPal takes minimum $0.30 per transaction

As you can imagine I often get emails with questions and cries for help. I actually enjoy these emails and try to help as much as I can. One of the issues I see is that some makers don’t know how to formulate a question to get the help they need. Just the other day I got an email from somebody who asked about a project I posted on Instructables a long time ago.

The project is for an oxygen analyzer to analyze dive tanks. The question was “ I get this weird error when I put sensor of make x on your sketch, what is wrong”? The problem with this question is it does not contain any information to find out what is happening. People are not able to help you if you don’t provide the correct information. If you ask this in a public forum people are not going to respond to your question.

Before you ask your question you have to do your due diligence. Below are some steps you have to take first before you ask for help.

What information do you need to supply?

You are asking for help, and may I add at no cost, you need to make it as easy as possible for people to help you. For example the person asking me about the oxygen analyzer should minimally have supplied what the error was and what changes he had made to the sketch.

If it is a question about a sample sketch that returns an error, you minimally need to supply what OS you are compiling on, the version of the Arduino IDE you use, and what libraries you are using, and of course the error message in as much detail as possible.  If you made alterations to the supply code give an explanation on what changes were made.

Minimal List of information you should supply

• Sample sketch
• Libraries used
• Arduino IDE Version
• What hardware used (Arduino related)
• OS version you compiling on (If it is a compiler error)

Before asking for help first find out what is wrong

Before asking for help you need to try to figure out for yourself what the issue is. By doing this you also have a better understanding of the problem. It will also help you to understand the answers you are going to receive. Here are some tips on doing your own trouble shooting before asking for help.

Trouble with your hardware

First make sure your hardware is working. You do this by testing each component separately. If you create a temperature/humidity data logger that uses a sd card breakout board, make sure that each component functions alone with your Arduino. First make a sample sketch with the temperature/ humidity sensor and see if you get the data you are expecting, and do the same with the sd card breakout.

I do this for all my projects. I first test each sub component separately before combining them. This way I know I wired everything correctly and know that is not the issue. If everything seems to work separately, and it stops working when combined all the components you know there is a conflict. Find out what components are conflicting by testing them with only an Arduino and two components at a time.

Note:In the beginning try to use components and breakout boards from the big guys like; Adafruit, Sparkfun, Pololu, Seeedstudio. They always have tutorials on how to use their components, and forums you can ask questions in.

Now you have done your homework, and are ready to ask people for help. First create a diagram with something like fritzing to give a visual representation of how the components are connected. Supply the sample sketch you made to work with these components, and give as much info about the versions, makes, and models of your hardware. By doing this you will get better quality of help, and avoid the trolls making nasty comments when you ask for help.

Note: A sample sketch is a sketch that only contains the code needed to show the problem. It is a fully working sketch, but paired down just to reveal what the problem is. It is a good way to trouble shoot, and to provide enough code to people to see what the problem is

Use your serial monitor to debug

The programmers among us know a bit about debugging and how important it is. Normally you can add breakpoints (a spot the program halts so you can look at the values of variables) to see what is happening, but because this is not possible with an Arduino we use the Serial.println() function to debug your sketch. This is often done because your project is not responding as you thought it would be. When I write a sketch it is always full of these Serial.println() statements to see what is happening. I normally remove them from the final sketch as it looks cluttery (if that’s a word).

For instance you press a button and your Arduino is not responding to it’s request. By simply seeing if your digital pin is high or low you can see if the button press has an effect, or maybe your if() statement is looking for the wrong answer. A simple Serial.println(digitalRead()) will let you know if the digital pin in question is HIGH or LOW. Look at the following example where I put lines in for debugging:

  buttonState = digitalRead(buttonPin);
  //Next lines are fo debugging
  Serial.print("buttonState: ");
  Serial.println(buttonState);
  // check if the pushbutton is pressed. If it is, the buttonState is HIGH:
  if (buttonState == HIGH) {
    // turn LED on:
    digitalWrite(ledPin, HIGH);
  } else {
    // turn LED off:
    digitalWrite(ledPin, LOW);
  }

This is often done in situations where complex calculations are in play using many different variable types e.g doubles, floats, and integers. By seeing what the actual value of these variables are before going into the calculation you can often find the problem.

Language Reference

Another common issue is when you are not sure what function to use or how to convert a data type. Before reaching out to someone, try going to the Arduino Language Reference page. This is an amazing resource with tons of information. This is my go to place when I am not sure what function to use, or what is the correct syntax.

Look here first and get an idea of what you want to use in your sketch and how to use it. Sometimes the information in this area is a bit thin and their examples could be better. If you get stuck and not sure how to get unstuck, that’s when you reach out to the community. First try to come up with an example sketch how you think it needs to go, and then post your question on your favourite place.

Sometimes just except the answer even if you don’t completely understand it

Sometimes the answer will be in the form of a cryptic piece of code that works for you but doesn’t make sense to you. Just run with it and try to figure out what part you don’t understand and google it. Most of the time (and it happens to me to) it is currently out of your scope of knowledge and will take a lot of reading, learning, and gaining more experience to understand it. As long as you know what part you don’t understand how to communicate with that code you can implement it in your code as a form of a black box (a black box is something you provide data to,  it gives you the answer, but you have no clue how).

In Closing

If you implement all of my recommendations, 80% of the time you will find your own answers. The 20% where you will need help,  you will look like somebody that wants help and shows that you have worked for it. It also gives the person answering your question an understanding of your experience level. Just saying “I am a noob” does not help when asking your question. If the correct information is not provided, people can’t help you.

Don’t be afraid to ask for help, but in the end you get out of it what you put into it. Don’t be embarrassed if you are not sure if what you did was right, if you show you want to learn there are many people out there who want to help you. Finally be proud of your accomplishments, and stand behind your work, even if you are not sure you are correct.  We all started off as a noob and had to learn and gain experience by asking the community for help. 

If you like this project and would like to see more of the same type, please subscribe to my newsletter using the form below or like  and follow my Facebook page. This way you get notified when a new post is available.  If you have questions or suggestions please email at akurk@thearduinomakerman.info me or leave it in the comments below. Have a great day and see you next time.

Subscribe to our mailing list

* indicates required

Email Address *

First Name

Last Name

Email Format

• html
• text

5 Tips To Improve Your Arduino Coding Skills

Please put some money in the tip jar by clicking on the donate button to support me so I can continue creating contend like this. P.S. please donate more than $1 as PayPal takes minimum $0.30 per transaction

I have been programming on and off in different languages throughout my 30 + year career for different reasons. One thing I learned quickly that all programming languages have one thing in common. You can write a fully functional program that 24hr from completion nobody can understand how it works; even the programmer her/himself is completely confused how it ever could work.

The first step in learning a new programming language is how to write legible code (in my opinion that is). It is tough to do when you start learning, but if you follow the 5 tips you will see the difference in how quickly you will improve you skills, and be able to reuse your code even months after you are done with the project.

5 Tips on improving the usability of your code.

Index

1. Use descriptive Variable names
2. Indent your code appropriately
3. Use Commends please
4. Use functions() to organize  and reuse your code
5. Document, document, document

1. Use descriptive Variable names

I see this so often;  int x=100;, or String y=”hello molly”;. It is completely legal, and correct to do so, but the names of these variables don’t say anything about what they do. Even if the x, and y in this example have something to do with plotting data on a x/y axis the names are too ambiguous.

Always give your variables names that make sense, e.g.  int x_Axis=100;. If you declare a variable for a digital pin that is going to be used with a button that turns an LED on, use button_led_on_off_Pin. This name has meaning. It tells you it has something to do with a button that is turning an led on and off.

In my opinion the only place where it is OK to use single character variables are in things like a for() loop initialization variable, or something similar.

2. Indent your code appropriately

Indent your code appropriately! If you have a nested if statements that are not indented properly it becomes really hard to read your code. It will be even harder to debug if you have a logic error (your code syntax is correct, but the code doesn’t do what you expected it to do) take this code example:

void loop() {
if(hedgehog==cat){
if(cat==likehedgehog){
  //hedgehog and cat are friends
}else if(hedgehog!=cat){
  //hedgehog and cat are friends
}else if(cat != hedgehog){
  //hedgehog and cat arn't friends
}
}else{
  //hedgehog and cat are not in the same room
}
}

Now see the next code example using indentation:

void loop() {
  if(hedgehog==cat){
    if(cat==likehedgehog){
      //hedgehog and cat are friends
    }else if(hedgehog!=cat){
      //hedgehog and cat are friends
    }else if(cat != hedgehog){
      //hedgehog and cat arn't friends
    }
  }else{
    //hedgehog and cat are not in the same room
  }
}

Notice how much easier it is to read your code. Your eye can see how these if() statements are nested and it makes it a lot easier to find your logic error. Sometimes I forget to add a closing bracket. You complete your code and get “expected '}' before 'else'” error message when compiling. In the indented code example it would only take seconds to figure out what bracket was missed, good luck to find the error in the non-indented code.

3. Use Commends please

Commends are part of the documentation process (but are not considered documentation) All programming languages allow you to give comments. In my opinion giving a short explanation what a variable is used for (at the instance of declaration) makes a lot of sense, and gives the person trying to understand your code (could be yourself three months after you finished) an inside what this variable is used for.

int cat=0; //If the cat is in the room the value is 1, otherwise the value is 0

If you have a complex nested if() statement or for() loop you could do something like this.

void loop() {
  int cat=0;//If the cat is in the room the value is 1, otherwise the value is 0
  int hedgehog=0;//If hedgehow is in the room value is 1 otherwise the value is 0
  int likehedgehog=0;//If the cat likes the hedgehog value is 1, otherwise value is 0
  int likecat;//If hedgehog likes the cat the value is 1, otherwise value is 0
    
    /**
     * This nested if() block is to check if the hedgehog and the cat are in the same room.
     * If they are in the same room we check if they like eachother 
     * If the cat likes the hedgehog everything is fine, if the cat doesn't likethe hedgehog
     * they need to be seperated
     */
    if(hedgehog==cat){
        if(cat==likehedgehog){
            //hedgehog and cat are friends
        }else if(hedgehog!=likecat){
            //hedgehog and cat are friends
        }else if(cat!=likehedgehog){
            //hedgehog and cat arn't friends
        }
    }else{
      //hedgehog and cat are not in the same room
    }
}

Notice that the extended description helps the person reading your code understand the function of this block of code. I also put an extended description at the top of my sketches explaining what the function of this code is, my name and sometimes my contact info, the date I finished, and the version of this current code.

/**
 * Author:Ab Kurk akurk@thearduinomakerman.info
 * Date:04/Dec/2017
 * Version 1.0.0
 * Description
 * This sketch is to be used to track the location of my cat and hedgehog.
 * The purpose is to make sure that today my cat likes my hedgehog.
 * 
 */

If I later on go back and I make changes I update the version, and give a description what I altered, what date, and who altered it at the bottom of the description block.

4. Use functions() to organize  and reuse your code

Functions might be considered a intermediate level , but even as a beginner it makes sense to try to do this. If you have big blocks of code that serve a specific purpose it makes sense to put it in a separate function. It makes your code more readable, and might also reduce the amount of code you write because it is easier to reuse the same code in a different part of your program.

As an example here is a piece of code from a previous tutorial I did about reading data out of memory. First without the use of a function;

void loop() {
  // put your main code here, to run repeatedly:
  String ssid="";
  String password="";
  /**
   * Reading the ssid out of memory using the eeprom library
   * The ssid starts at memory position 0 and is 30 characters long
   */
  
  for (int n = 0; n < 30; ++n)
    {
     if(char(EEPROM.read(n))!=';'){//looking for end of data character ';'
        if(isWhitespace(char(EEPROM.read(n)))){//Remove whytespaces e.g. a space 
          //do nothing
        }else ssid += String(char(EEPROM.read(n)));
      
     }else n=31;
    }

  /**
   * Reading the password out of memory using the eeprom library
   * The ssid starts at memory position 100 and is 30 characters long
   */
  
  for (int n = 100; n < 130; ++n)
    {
     if(char(EEPROM.read(n))!=';'){//looking for end of data character ';'
        if(isWhitespace(char(EEPROM.read(n)))){//Remove whytespaces e.g. a space 
          //do nothing
        }else ssid += String(char(EEPROM.read(n)));
      
     }else n=131;
    }
}

You see that we have two blocks of code doing the exact same thing. Here is an example of the same code but using a function;

void loop() {
  // put your main code here, to run repeatedly:
  String ssid="";
  String password="";
/**
   * Reading a string out of memory using the eeprom library
   * The read_string(length of data int,position in memory int) is a function
   * you call to read data out of memory. You give it the start position
   * in memory and the length and it returns a string containing the data
   */
  ssid=read_string(0,30);//read ssid out of memory
  password=read_string(100,30);//read password out of memory

/**
 * Reads a string out of memory, l is the length of the data to be read out of memory,
 * p is the position in the memory where to start reading 
 */
String read_string(int l, int p){
  String temp;
  for (int n = p; n < l+p; ++n)
    {
     if(char(EEPROM.read(n))!=';'){
        if(isWhitespace(char(EEPROM.read(n)))){
          //do nothing
        }else temp += String(char(EEPROM.read(n)));
      
     }else n=l+p;
     
    }
  return temp;
}

You can see that I reused code by creating a function. This makes it easier to read, and uses less memory on your controller board. If you get proficient at using functions you will save time  and create more user friendly code that you can reuse in your next project

5. Document, document, document

The documentation of your project is probably the hardest, and the most boring thing about your project. To me it always felt like a annoying  task that wasn't really needed. To clients and employers it is often seen as a waste of time and money. The reality is that it always will save time and money on the back end of a project.

 In my documentation I always have a software section and a hardware section of my arduino project.

The software:

• The libraries I used, the versions, and where I got them from if I downloaded them.
• All the functions I created and a description of their function and what line you can find them.
• Any methods and their children
• A full explanation of what the sketch does, and how to use it.

The hardware section:

• I put in a schematic of how to connect it to my development board. I often use the fritzing program for this. It is easy to use and free.
•  Each breakout boards and sensors that is used in the project, what pins I connect them to. I also note down what software libraries are needed for this hardware.
• If it is an exotic sensor or breakout board I also note down where I bought it

In Closing

If you adopt all or some of  these tips, you will become a better programmer/maker. It also means that if 6 months down the road you do the same type of project you can look back at your previously completed projects and reuse your code and ideas and not constantly have to reinvent the wheel.

I know out of experience that it looks a lot easier and spent less time not doing all this and just write code without formatting and documentation, but you would be wrong.  I often wasted so much time trying to understand why I did something a certain way, or was trying to figure out why a variable changed values just because I reused it in the wrong way.

If you like this post and would like to see more of the same type, please subscribe to my newsletter using the form below or like my Facebook page. This way you get notified when a new post is available.  If you have questions or suggestions please email me or leave it in the comments below. Have a great day and see you next time

Subscribe to our mailing list

* indicates required

Email Address *

First Name

Last Name

Email Format

• html
• text

Helpful Tip: How to create a more professional and user friendly Arduino project by storing your configuration in the EEPROM

Please put some money in the tip jar by clicking on the donate button to support me so I can continue creating contend like this. P.S. please donate more than $1 as PayPal takes minimum $0.30 per transaction

As makers we strive to make projects that are easy to use and have a more professional feel about them. If your project is user configurable (e.g. are you using C or F for your temperature), how do you store that information so it is kept, even when the Arduino gets reset?

 What if you could make your Arduino remember these types of user changeable settings (e.g. using a menu saving your Wi-Fi password)? The solution is using the EEPROM library. This library allows you to store your configuration data like your WIFI router name and password, and be able to change it if you get a new router or password. The drawback is that you can only write and erase data 100,000 times so be careful to only write the most important data. Luckily you can read this data as many times as you want without any issue.

To write your data you use the; EEPROM.write(address, value), and to read your data you use the EEPROM.read(address). The drawback is that writing anything other than an integer can be complicated.

In the next weeks, I will be writing a tutorial on how to write your configuration or other information to your Arduino/Compatible so you too can create professional looking projects.If you are interested subscribe to my periodical Newsletter by filling out the form below, or follow me on Facebook by clicking on this link, and click the follow button. 

Subscribe to our mailing list

* indicates required

Email Address *

First Name

Last Name

Email Format

• html
• text