What’s up, bros and broettes ? Welcome to a new series about the ESP8266. This ongoing work focuses on how to interface specific peripherals to our beloved Chinese wonder. In this context a peripheral is an individual chip, component, sensor or actuator. It can also be one of the internal peripherals of the ESP8266.
Each article in this series will focus on a single peripheral device, for which I’ll write a library or “driver“. In my introductory series I basically gave you code to paste in Eclipse. That was to point out how simple it is to program an ESP8266. This series is different : all its code will be stored online under version control (GitHub) to give you reliable access to the source directly from Eclipse. The articles themselves will cover the hardware aspects, theory of operation, and example applications.
This is not an introductory series, we’re past that and there’s no turning back. Things will get serious and skillz will get mad.
But first, eat your veggies
If you so choose, you’re about to embark on serious software development, the kind that produces results. As opposed to hacking, which is an over-glorified term describing activities akin to pissing in the wind and hoping it doesn’t fall on your shoes : exciting in the beginning but it always ends in tragedy.
The main aspect of serious software development (the successful kind, that actual employers pay actual salaries for) is formalism. In other words, having a track from idea to product and staying on it. And that means you need to lay some track before you start coding. That groundwork is as sexy as geeks used to be, but it pays off way sooner than you’d expect and it doesn’t take very long. In fact, I’ve deployed my usual genius to ensure that you’ll get set by the time you finish reading this article.
Or you could be the impatient type and move on to the fun stuff right away. I know that type, the type that goes nowhere fast. You do not want to be that type. You want to work like a pro and get sh… done, not hit the fan with it. So read on.
First, setup your software design environment
If you’ve gone through my introduction to the ESP8266, you’re already set and can skip to the next section.
You don’t need to read that whole series, although you should, but you really need to go through that particular article. It will show you how to setup a complete software development environment for the ESP8266, similar to what Espressif uses to create the firmware that ships with your ESP8266 modules. It’s also the same environment Nefastor himself uses. It does get better than that… and you’ll get there too by the end of this article.
Once you’ve got Eclipse and the Unofficial SDK, go through the project described in that other magnificent article. You might not care about blinking an LED, but it’s best you make sure your environment and modules work. Also, you’ll learn basic information about the ESP8266 that will always come in handy.
We’re going beyond simple experiments and entering the realm of production-grade code. This means two things :
- The libraries or “drivers” I’ll be publishing will be significantly complex.
- They may also be subject to future updates.
Therefore I will be using an online version control system. I’m aware you might not know what that is or how to use one, and we fear the unknown, so this article will cover that. You’ll want to follow my instructions closely : yes, you could perfectly download my code and copy my source files to your workspace manually, but I’ve gone to the trouble of making things easier and safer for you. So why shoot yourself in the foot ?
Git is the version control system developed by Linus Torvalds as part of the development of the Linux kernel. Git makes it possible for several developers to work together on the same software project, remotely, without stepping on each other’s toes. Just as Linux, it is free software.
Git manages repositories : think of a “repo” as a folder containing everything about a project. Not just code but also data, resource files, documentation, tools, test patterns and anything else you can think of that can be stored on a computer. A repository also stores the history of its modifications, which allows you to return to previous known-good versions. Hence the name : version control.
GitHub is a web-hosting service for Git repositories. It offers free services provided your repositories are public. Public means you’ll be able to clone this series’ repository and get all its future updates.
The Nefastor/ESP8266 repository
But what’s in that repo, exactly ?
In its initial version (which you could check out right now) it contains a template project identical to the one I described in my introductory series. You can compile it, flash it to your module and an LED will blink. With each article in this series, I’ll add a new library or “driver” for a specific peripheral to that template.
Follow the instructions in this article and you’ll create a clone of my repo on your computer that you can use to jump-start your own ESP8266 projects. You’ll be able to update your repo any time I publish a new article so that your future projects include its new libraries. And those updates won’t ever break your projects based on previous versions of the repo. Most importantly, you’ll do all that directly from Eclipse, without messing with any files.
My goal here is to create a code base that lets you start your projects with all the boring stuff already taken care of and validated. I do this sort of stuff for myself all the time and now I’ve decided to share. Lucky you !
GitHub / Eclipse integration
If you’ve done what I’ve asked you to (and why wouldn’t you ?) you now have Eclipse installed on your computer and setup for ESP8266 development using the Unofficial SDK. We will now give Eclipse the ability to work with GitHub because this ain’t the dark ages anymore.
Launch Eclipse and open the “Help” menu. Select “Install New Software“. Once that dialog box opens, tell it to “Work with” the following site by pasting this URL in and hitting Enter :
After a little while the dialog box will offer you several packages to install. You only need one, “Eclipse Git Team Provider” :
Once you’ve ticked it, hit “Next“. Agree to everything that happens next, after all it can’t be worse than the Apple terms and conditions and we both know you never read those before you agree to them. Even after you watched that South Park episode.
Eventually, you’ll be told to restart Eclipse. You should do that.
Congratulations : through no fault of your own you have successfully installed EGit, the Eclipse plug-in for Git.
Pimp your Eclipse
You’ll notice that nothing has changed. Well… of course something has, but it’s very subtle. We’ll get into it little by little. For now, make Git easier to use by activating its toolbar. Open the “Window” menu and under “Perspective” select “Customize Perspective“. The dialog that comes up has an “Action Set Availability” tab : get in there and tick “Git” in the left column. Move on to the first tab (“Toolbar Visibility”) and if it hasn’t happened automatically, also tick Git. Click OK and you’re done.
Final bit of interface customization : Return to the “Window” menu, navigate into “Show View” and select “Other“. A dialog box comes up : expand Git and select “Git Repositories“.
And of course, hit OK. You’ll get a new Git Repositories tab at the bottom of your Eclipse. At this point it will show this :
Time to clone !
I know it’s never a good idea in the movies, it always ends terribly, but when it comes to Git ? Cloning will save you a lot of time and spare you a lot of trouble. It’s how you’ll best be able to enjoy the code I’ll be writing for each article in this series. You’ll get straight into Eclipse. No messing with files and folders, downloads and copy-pasting.
Click “Clone a Git repository“. A foreboding dialog box lurches into view, asking for arcane mysteries. You only need to give it the URI (web address) for my repo : https://github.com/Nefastor/ESP8266. The authentication is your GitHub login if you have one. I believe you only need one if you’re going to commit changes to my repo, and I’m not about to let you.
Hit Next : Eclipse will ask you which branch of my repo you wish to clone. Always choose the master branch : it’s the best and latest code, with no experimental features.
Hit Next again : now you need to specify where you want Eclipse to store your clone on your computer. Your Eclipse workspace might seem a logical choice but it is strongly discouraged by the good people who maintain Eclipse and EGit. Choose some other place and try to avoid spaces in the path. I use “C:\ESP8266_Git”.
Tick “Import all existing Eclipse projects after clone finishes” so you can start using the repository immediately.
Hit “Finish“. When cloning completes, you’ll have a new project named “ESP8266_Template” in your Eclipse Project Explorer pane, stored on your computer, ready to build, flash and run. Don’t forget to adjust the makefile’s COM port variable to match the one your module uses.
Because it’s under version control, the project’s entry in Eclipse will look a bit different, indicating the local repo and branch.
The big idea
As I proceed with this series I’ll add code and improvements to my repository. You’ll be able to update your clone repository to match mine. That means you should not modify your repo. After all, templates aren’t meant to be modified, right ?
Instead, and just as I’ve shown you in the introductory series, any time you want to start a project based on that template you should copy the template project from inside Eclipse. Eclipse will place the copy in your workspace. You can then rename it and start coding.
Proceeding this way, your new project is now decoupled from your clone repo, which means that any update to your repo will not impact your own projects.
This approach is guaranteed to maximize your efficiency, making your life easier, and minimize Git-related mistakes, making my life easier. Of course you’re free to do whatever you want on your own computer, but this is the paragraph I’ll be pointing you to if you come to me crying that updating your repo broke your code.
Grabbing updates from GitHub
After I post a new article, you may want to get the code that comes with it. That’s so easy this section is going to be the shortest of the whole series.
Select the template project in Eclipse, open the “Git” menu and click “Pull” (the one without the “…”, otherwise it’ll take one more click). Git will compare your clone repo against its (my) original on GitHub and, if they are different, it will fetch my master branch. Then Git will try to merge your clone with that fetch. If you haven’t tampered with your repo, everything will go smoothly and you’ll end-up with an updated repo.
Cloning : the more you know
So you’ve got a clone of my repository : what is it, actually ? Well, true to the meaning of the word, it’s a new repository identical to mine, but stored on your computer. That means you don’t need to be online to use it. You can back it up if you feel the need.
You can also create your branches to track your own modifications to your clone repository, though it will complicate things if you ever want to pull in modifications I made to my repo. Leave this for when you’re comfortable using Git.
Your repository still points to mine, its “origin”, so they can interact. For instance, this lets you grab new versions of my code without re-cloning. And it would also let you commit changes to my repo… although at this time I don’t plan to give anyone that privilege. Show me you’re worth it, and that may change.
Ah, and of course you can create as many clones as you want, even though this defeats the purpose of using version control.
Congratulations on eating your veggies. If you’re into ESP8266 programming it’s very likely you’re doing this as a hobby. This makes it very likely that you’ve never read such a boring article in its entirety before. But you’ll be glad you have. Sometimes you don’t know you need to learn something until you do : you’ve been to school, you know what I mean.
For your patience, here’s you’re reward : from here on in, this series will only deal with “useful” stuff. Fun stuff. Stuff that will get you laid. Like interfacing relays and gyroscopes and OLED displays.
I’ll start with shields meant for the WeMos D1 Mini we’ve been using so far. Don’t be fooled, though : while the D1 Mini and its shields provide a good starting point, the true focus is whatever component is actually doing the job. The WeMos boards are development kit and we’ll use them in that capacity. Yes, you read that right : Nefastor can actually use something for its intended purpose. Because he is the alpha and the omega, and every letter in between, plus the hieroglyphs.
See you then !