DEV Community: William Otieno

Beginner's guide to Git and Open-Source Contribution

William Otieno — Sat, 17 Oct 2020 15:22:08 +0000

Introduction

There are a lot of skilled developers from around the world; ranging from web developers, android engineers, DevOps engineers, sys admins, IoT devs to simple script kiddies...but there is always one thing that ties them down; getting 3rd-party assistance. That's where open-source contribution comes in.
Well, there are a number of definitions regarding what open source is, Wikipedia defining it as "denoting software for which the original source code is made freely available and may be redistributed and modified" but I see it more as software of the people, for the people and by the people.

In order for software developers and engineers to contribute to particular projects without the need to be physically present, a version control system (VCS) was developed. Well, it's not only about remote contribution; just as the name suggests, version control also enables one to revert back to a particular moment in time just in case he/she made a mistake developing software. Over the years there have been a number of VCS that were implemented but Git became the most popular.

This article will focus on the absolute beginners, we will go through the fundamentals only as Git is very wide. But not to worry, you will have mastered essentials in just a couple of minutes.

What is Version Control?

When you are working on a simple project, such as a single page html, it is fairly easy to remember the last thing you changed and where the development is headed. But tracking revisions over time, also referred to as version control, quickly becomes more complex when you are working on a large project with multiple files and multiple developers.

You not only want to record changes, but also who made the changes, and when. Managing revisions at this level requires a version control system.

Version Control Systems (VCS) help a software team manage changes to source code over time.

VCS software includes tools for saving the state of a project, viewing the history of changes, and reverting changes.

Developing software without using version control is risky, similar to not having backups.

VCS can also enhance and speed up development. Depending on the version control software used, many developers can work on the same code at the same time.
For example, one developer on the team may be working on a new feature while another developer fixes an unrelated bug, each developer making their changes in several parts of the code base.

VCS even have tools to prevent conflicts when one developer's changes are incompatible with changes made at the same time by another developer.

Git vs Github

Git became the most popular VCS system since its onset in 2005. It was made mainly as a result of necessity since a lot of developers needed to contribute to the Linux Kernel. It's main advantage was that it was distributed - rather than having only one single place for the full version history of a project, every developer's working copy of the code is also a repository that can contain the full history of all changes.

You should however note that Git is somewhat like an engine and Github is a platform that enables users to exploit git.

Hands-on Lab

Getting Git

For *nix systems(Mac/Linux), git should be installed in your system by default. If not, there is a quick installation guide for all platforms here.

Initializing a Git repository

I'll try to explain how this works in the simplest form. This is how everything is... You have a local repository (storage) and a remote repository. The local repo is essentially in your computer and the remote repo is online in a particular platform (maybe Github or Gitlab). So what happens is that you will mostly write code on your local machine then push those changes to the remote repo where other members can see what you did and in essence pull those changes from the remote repo to there local repos. It's just like uploading and downloading in a way.

Let's just jump right in for this to make sense.
We will first create a directory(folder) then make it a local git repository so that git can track every change happening to it.

Launch your command-line interface (terminal for *nix users and the git command-line for Windows users)
To create folder, it's just as simple as running mkdir foldername
Let's name it devstuff
As of now, it is just a folder named so. We then have to further make it a git repository (like a git storage). We do this by navigating into the folder using the cd command and executing git init (initialize git repo)
So in my terminal...

As you can see, we got into the directory and it was at first just a directory. After initializing git, it becomes a git repo. What it does is that it creates a git folder of sorts but it is hidden by default hence named .git as seen by the generated path above.
Well, we now have our local git repo. Let's make a remote repo on Github then connect it to our local repo.
You should first create an account on Github and sign in.
Navigate to the top right corner and click on the + button and select New Repository

For ease, we shall give it the same name as our local repo devstuff and put in some little description and create the repo.

You should encounter a new page with this...

Let's break down what we can see then...

Well, we already did most of the essential stuff on our own so the only command we should run is git remote add origin https://github.com/WilliamOtieno/devstuff.git
That will simply link our local repo to our remote one. In short, we are adding the remote repo from origin to our local repo. So that information will be contained in the .git hidden directory.
In our terminal...

Let's add a file so that we can track the changes. You can use your file manager to do so or in the terminal execute touch dev.py
It will be some simple Python code with a simple print statement.

Running a simple listing ls command shows that our file is present.
We can take it a notch higher by running git status to see...well, the command is self-explanatory

Git Tracking

When working with files, git by itself has a particular workflow to get things done. There are 3 states in which a file exists:-

Untracked
Staged
Committed

Finding the actual status of files opts us to implement the git status command as seen earlier.

Untracked means that git is not currently tracking any changes on the file, staged means that git is tracking changes on the file wheareas committed means that a snapshot of the current state of the file has been taken with a simple message (commit message) of what happened in particular.
Let's add 2 other files so that we can really understand what's going on. For that, use your file manager or simply use the touch [filename] command. I'll add a README.md file and maybe a requirements.txt file.
Now, to essentially move a file from the unstaged/untracked area to the staging area, we should use the git add [filename] command. In your CLI...

As we can see, we staged our python file but the other ones remained in the unstaged area. So after staging, we should commit our change. We do this by running git commit -m ['message']. In our case...

You should however note that commits are only applied to files on the staging area. The remaining ones remained untracked.
Most times one will be working with dozens of files so to add all untracked files in the local git repo to the staging area, we implement git add .
Take note of the position of the dot.
This will add everything in the current working directory so it's like adding all the contents of the working directory. Another command would be git add * which in essence means adding everything. Let's try it in our command-line and check the status...

Let's try writing something to our README.md file then check the status. You can use your favorite text editor or do this one-line command in bash...
echo "### I love Git." >> README.md
That will simply print out the text but redirect the output to the README.md file thence writing to it.

As you can see, the file was being tracked. Git has automatically detected that it was modified so we have to commit our change using the git commit command.
Consider a situation where you had staged all files in a repo and you simply want to unstage it so that git doesn't track any changes. For that scenario, one should exploit the git rm --cached [file] command. In our case, let's unstage the requirements.txt file and check the status.

Now our requirements.txt file is untracked.
But constantly having to see that portion telling us that a file is untracked when we want it that way is rather annoying so let's consider a scenario where we do not want git to track some files. For that we use a .gitignore file. It is normally hidden and doesn't have a file extension. So let's create and use it. In your CLI, just use the touch .gitignore command. Or in your file manager, create a file and name it .gitignore but don't append any file extension to it plus don't forget the preceding dot.
After that, open the file and just write the name of the file(s) you want git to ignore. For multiple files, each file name should be in its own line.
Since .gitignore is a new file, stage it and commit the changes and then run the status check again.

Pushing to the remote repo

At this point, we are ready to push our changes to our remote repo in Github. But before that, I'm sure you have questions about the output from our last command "On branch master..."
Well, that will be on the next article but basically, git organizes repositories in branches such that one can avoid messing up the production or main branch. By default, the main branch is normally called master and that's why it's there. Not to worry, it's nothing complicated.
So let's push everything we've done so far to our remote repo. But at first, we shall verify that we indeed have nothing there. So go to Github and search for the repo (we named it devstuff).

As you can see, there is no code but some guide to get started. But before that, we should set up our credentials in our git command-line before pushing. You should use the same name and email address as the ones in your Github account.
Do so by running...
git config --global user.name "YourName"
git config --global user.email"youremail@yourdomain.com"
Now let's push the code. It will be a simple one-line command...

git push -u origin master

You'll be prompted for your username and password. The password field is normally blank when typing for security reasons so don't be alarmed.
The -u flag is used to tell git that we are pushing the repo upstream and the next time we push without the flag, it should remember that we want to push upstream. Also, origin is the default name of our remote repo so in essence we are pushing upstream to our remote repo called origin and into the branch called master.

Refresh your browser tab and voila! You'll see that the code is now present. The remote repo will contain the commit messages and commit times as well.

You could also click on the individual files so as to view the contents.

Conclusion

Git is not as complicated as people perceive it to be. This is only the 1st part of a 2-series article but the remaining chunk is not as lengthy. Actually, this is enough to get one started to open-source contribution. For any queries, just follow and send a message to my Github here.
Thank you for your undivided time and attention.

Using Python for Arduino Projects

William Otieno — Mon, 28 Sep 2020 17:29:03 +0000

INTRODUCTION

Every hardware engineer and IoT enthusiast has interacted with a number of micro-controllers and embedded devices, the most common one being the Arduino micro-controller. Well, it's a good fit for noobs who want to get their feet wet but the only caveat is the C/C++ hybrid language used in the Arduino IDE as most devs find it quite intimidating.
Today, I'm going to take you down the rabbit hole with me by showing you how to use Python to program your Arduino micro-controller.

REQUIREMENTS

For starters, you'll need the following hardware:

Arduino (UNO, Mega2560...etc)
Arduino USB Cable
LEDs
Push Button
10kOhm Resistors

Well, the only software requirement is the Arduino IDE

EXPLANATION

The theory behind what we are trying to do is communicating with the Arduino using a serial connection between our computer and the micro-controller itself. There are a number of ways this can be achieved; in Python for example, the PySerial library can come in handy, effectively capturing serial data transmitted between the board and the computer. But that's an article for another day.

In this article we are going to exploit the Firmata protocol which is already available by default in the Arduino IDE post-installation. This protocol establishes a serial communication format that allows you to read digital and analog inputs, as well as send information to digital and analog outputs.

Uploading the Firmata Sketch

Let's dive right in and see what we can do. The Firmata sketch is (as I said earlier) already available in the Arduino IDE so on your desktop, launch the IDE and navigate to File then Examples then Firmata and click on the StandardFirmata sketch.

An alternative window will be opened upon which you should select your appropriate board type and port after connecting your board to your computer via a USB cable. Compile the sketch and upload.

Python Fun

Now let's play with some Python code. You will need to install the pyFirmata package through the Python Package manager, pip. Now, for *nix systems i.e (MacOS/Linux) launch your terminal and for Windows users, launch your command prompt then run the following command:
pip install pyfirmata

You should get some result similar to this...

After installation, launch your favorite text editor, in my case, I'll write the Python code on an open-source version of VS Code. We'll now write some simple Python code equivalent to the Blink Sketch (The Hello World of Arduino😉).

Now let's crack every bit of the code (pun intended😉).
So we first import the library we need to establish a serial connection between our board and the computer. Our plan is to control the inbuilt LED connected to pin 13 on the board so it will be prudent to use the time module in order to control how long we will turn the LED on/off.

Since communication is through a serial protocol, we need to define our port. You can get this info from the Arduino IDE and for my case it is as stipulated above. For Windows users, it may be COMx where x is any integer.
We then instantiate our board object (myBoard) and pass the port as an argument to pyfirmata.Arduino()

The next step is to run the main block of code in a loop just like in the Arduino syntax. So let's use a while loop for that...
board.digital is a Python list containing all the digital pins of the Arduino but in our case we are using pin 13. The .write() method is used to write the state to the digital pin. The state is represented as either 1 or 0 for HIGH or LOW respectively. The former representing 5V and the latter 0V hence high or low.
The HIGH state provides 5V to the LED and turns it on while LOW state provides 0V hence turning it off. The .sleep() method from the time module is responsible for handling how long each action takes; just like the delay() function in the Arduino syntax.

Running the Code

We can now run the code by launching a terminal and executing:
python pyduino.py
You should however note that the proper syntax is:
python [filename.py]

Now wasn't that simple. Let's go even deeper by adding a push button that will change the state of our digital pin...

More Hands-on Experience

We shall first connect our circuit as follows:-

The Button is connected to a 10k pull down resistor so as to ensure the voltage is completely pulled down to 0V on the digital pin.

Our code will only change a bit and it will be just as simple as the other one:

We are conversant with line 1 through 5. Line 6 is used to define an iterator that will constantly read the state of our digital pins. Line 7 only instantiates or activates it.
Line 9 explicitly declares digital pin 10 as output through the pyfirmata.INPUT method. This is necessary since the default config use for digital pins is as output and not input.

We then go to our loop and define our switch pin. The rest is as intuitive as it gets.
The final step is obviously running our Python script and Voila! Some action.

CONCLUSION

Micro-controllers and Embedded Devices are on the rise in numerous applications especially in the Internet of Things(IoT). Enthusiasts, hobbyists, Engineers, and other developers are getting the chance to explore numerous possibilities by building projects and contributing to others.
For the Arduino fans, this article is only a tip of the iceberg. The journey is a deep dark rabbit hole that once you get yourself into, there's no turning back. This also applies to Python programmers who just don't like C/C++.
For those interested in learning more, there is excellent documentation on Pyfirmata here that will be of great use.
For those who want to do IoT natively in Python, then there are other Micro-controllers such as MicroPython and the renowned RaspberryPi. But baby steps first😅; we all start from somewhere.

Anyway, that's all for now. I hope you enjoyed.
Thank you.