-
Notifications
You must be signed in to change notification settings - Fork 2
Getting Started
-
What we do
-
Project
2.1. Overview
2.2. Hardware we use
2.3. Software we use
-
Step-by-step guide to running the codebase for the first time
-
Workflow
-
Extra readings and references
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.