-
Notifications
You must be signed in to change notification settings - Fork 2
Getting Started
We are the firmware subteam, part of the UBC Sustaingineering Electrical Team. If you are new to Sustaingineering, check out the Welcome Package.
The firmware team is working on the Enicalsa Solar Pumps project, trying to collect data on the operation of solar-powered water pumps to monitor their function and allow engineers to detect and fix issues rapidly. See one of Enicalsa's solar pumps here.
We are using microcontrollers to read data from sensors and relay the information to a webserver, where Enicalsa can view the report through a website. This document will help you understand the software and hardware we use to do this, and put you on your way to contributing to this project.
A high-level network diagram is available here
The solar panels are installed by Benito, and are external to our system. They are the source of our data, but their operation is outside of the scope of this project. A microcontroller will collect data from the solar panels, using the sensor suite developed by our team. Typically this will be the cheaper ESP32, which communicate with each other via LoRa, but there must be at least one Particle board per network. The particle acts as the gateway between the ESP32 network, and the outside world. It sends data between the farm network and the internet server through mobile internet. Once data is transmitted to the server, it is published to the internet and can be accessed from anywhere. This dataflow is bidirectional, and data may be sent to the ESP32s and Particles, such as for firmware updates.
The ESP32 is a microcontroller which is used to read sensor data, store it to an SD card, and relay the data via LoRa to the Particle. There will typically be one ESP32 per pump. The ESP32 is small, low power, inexpensive, and compatible with the Arduino environment, making it convenient to use. More information, including the datasheet, can be found on Notion in the page ESP32 Docs.
Particle is a company that produces microcontrollers with integrated telecommunications hardware, and a subscription to a data service. We use both the Electron and the Boron boards (the Electron is discontinued). The board may collect data from a sensor suite, similar to the ESP32s, but the primary function is to connect the network on the farm to the internet server. There will be one Particle on the farm, which will communicate over LoRa with the ESP32 network. It also has mobile data, and so it can send the sensor logs to the webserver directly. However, the Particle board is much more expensive than the ESP32, and also has a recurring cost for the data plan, so only one of these is used per farm. More information on the Particle boards can be seen on Notion at Particle Evaluation
LoRa (Long Range) radio is a network architecture that allows for communication over several kilometers without relying on external structures (like telephone towers or satellites). We use breakout boards such as the RFM95W for our LoRa radios. This makes it easier to connect to the microcontroller with through-hole pins for testing purposes. We use the RadioHead library to drive the LoRa on both the Particle and the ESP32
The microcontrollers read data from a sensor suite, which will eventually be embedded in a PCB. The data includes things such as the temperature, water flow, voltage output from the solar panel, and so on. This data is converted to digital values by the microcontroller, and passed along the network. There is another team within the Electrical Team working on the PCB. From the perspective of the Firmware Team, the PCB is a blackbox.
The solar panels and pumps are installed, maintained, and operated by Enicalsa. Our job is to measure information about these stations, and Sustaingineering has a replica station set up at the UBC Farm (which is maintained by the mechanical team), but beyond this test station the operation of the solar panel and pumps are outside of the scope of our project.
The internet server receives data from the Particle, and uploads it to the web. The Software Team built a web app which can process and analyze this data, and display it on a website accessible from anywhere. The Firmware Team must make sure that the data is encoded correctly by the Particle so that it can be interpreted correctly by the server, but beyond this point the server is a blackbox.
Git is a very common tool used in industry and hobby projects. It is a vast and complex topic, but you only need the basics for now. We use GitHub as our remote repository (online backup). Git is a version control system. This means that it doesn't just save your work, it saves the changes you've made in your work. This has a couple of advantages over something like Dropbox: first, if you make a change and accidentally break the program, you can always roll back to a version that you know worked. Second, if you want to work on one part of the code whilst another team member works on a different part of the code, you can simply work in your own branches on your own computers, and Git makes it easy to combine your work once you're done. If you have never used Git before, start with this walkthough. You can follow the guide and try making your own repository (repo), although ultimately you will be working in our repo. You may also want to keep this cheat sheet handy.
An example image of a Git workflow is here. The 'Master' branch (blue) should never have any bugs in it: you only commit to Master when you know everything works. For each new feature that you want to implement, you should check out a new 'working branch' (green). Either you get the feature to work correctly, and you merge with Master, or the feature is dropped, and the branch can be deleted.
GitHub is a website which hosts Git repos online and provides some useful extras. In fact, you're on GitHub right now!
If you want to use GitHub on your own, here's a handy quick-start guide. But the parts of GitHub that you will be using are all pretty intuitive, so feel free to just poke around and see what our team is doing. The most important features we're using are:
- Code hosting As mentioned, GitHub is where we host our git repo. This means, when you want to back up your code or see what other members have been working on, you can push or pull to 'remote'. This will synchronize the code on your computer with the code that's saved on GitHub.
As well as being able to view the code on your computer, you can also see the code at github.com/Sustaingineering/Pump-Firmware. By default it will show you the master branch, but you can choose which branch to look at. you can click 'View code' to see our code directly online, and you can even edit it straight on the website (although this is not recommended).
- Task management If you click on 'Projects' in the top bar (or click the link here), you will see our ongoing projects. Most tasks will be in 'Common'.
Once you have navigated to 'Common', you will see a kanban board. You may be familiar with kanban boards from apps such as Trello, or you can click the link provided to learn more. Essentially, they are a way to organize and collaborate on tasks in a clear visual format.
When you are given a task, the firmware lead will the task to the 'To Do' list, and assign the task to your account. In GitHub, this will create an 'Issue', along with an automatically generated number. When you start working on the issue, you will create a new branch with your issue number and a brief description. For example, if you are tasked with reading the temperature on the ESP32 and the issue number is 99, your branch name might be #99-Get-Temp-On-ESP. You can also then move your issue from the 'To do' board to the 'In Progress' board.
- Error checking When you run your code, the compiler will automatically try to detect problems and tell you what's wrong. GitHub has a similar feature, and it is located under the 'Actions' tab. You don't need to worry about what's going on behind the scenes just now.
GitHub will automatically try to build any code that you push to a branch on GitHub. It may take a few minutes, but the report will show up in the Actions tab and tell you whether the code built successfully. WARNING: Code may build fine on your local machine, but fail to build on GitHub! Usually this is because you forgot to add a file to your commit.
Before you merge with master, you must make sure that your branch builds on GitHub!
VSCode is an IDE (Integrated Development Environment) made by Microsoft. You must use this IDE, because our setup requires VSCode extensions.
VSCode is easy to get started with, but has some powerful advanced features. If you haven't used VSCode before, you can start with this introductory video, or just jump right in. Just make sure to install the C++ extension.
PlatformIO is a VSCode extension that makes it easy to write and run Arduino code for the ESP32.
PlatformIO allows you to build and upload your code to the ESP32 (but not the Particle boards), as well as to communicate with them over a serial interface (i.e. over USB). You can read more in their Quick Start guide.
Make sure the PlatformIO is disabled when working on the Particle.
Workbench is a VSCode extension that lets you run code on a Particle board, such as the Electron or Boron.
Workbench allows you to build and upload your code to the Particle boards (but not the ESP32), as well as to communicate with them over a serial interface. You can read more in their Docs.
Make sure the Workbench is disabled when working on the ESP32.
RadioHead is a library that provides network communications functions for a number of microcontrollers, including the ESP32 and the Particle. It is already forked in our repo, and our code relies on many of its functions.
Included in our repo are a number of example programs which demonstrate how the library can be used. You can also read the official documentation here.
Notion is the homepage of Sustaingineering. All of our teams have pages here, and this is where most of our files, documentation, meeting notes, and more is stored.
If you haven't already, be sure to read Intro to Notion
Microsoft Teams is our communication platform. This is where we chat with each other, video call, and hang out.
If you don't already have Teams, read Setting up Microsoft Teams. Teams is similar to Slack, so if you have used that before you will probably find Teams easy to pick up. You can read more information on using Teams here.
NOTE: UBC has disabled a number of features for privacy reasons. One of the biggest downsides is that your Teams name is your CWL, which is often hard to guess. For this reason, we have created a list of MS Teams names on Notion, which you can reference to find out who is who.