PacMan Firmware

This repository contains the firmware code for Lafayette College's 2019/2020 PacMan Board. It is written in C/C++ with extensive use of Arduino & ESP-IDF specific functions and libraries. We also have rather extensively modified the CANopenNode library to work on the ESP32 and the ESP-IDF's CAN driver. Branches are used in this repository and it is recommended to check other branches for the bleeding edge.

Description

This project provides the firmware for the ESP32 processor used on the PacMan board. It provides essential functions for the board, including but not limited to, CAN Bus communication via the CANopen protocol, Pack e-ink Display operation, I2C-based CellMen communication, and other various important operational and safety checks.

Tested and working on PacMan board version: 1.3

Getting Started

1. Install the Arduino IDE. Tested on version 1.8.10
2. Add ESP32 board to the Arduino IDE by adding this Additional Board Manager URL: https://dl.espressif.com/dl/package_esp32_index.json. A tutorial is located here
3. Select the ESP32 Dev Module in the boards list - Though most of the common boards here listed here will be compatible
4. Clone this Github repository. A tutorial for git can be found here. We recommend also using Github Desktop or IDE with Github support like Atom or Visual Studio Code; the latter of which can also be used to easily programme and upload to the board if you are not a fan of the Arduino IDE.
5. Open up the file: PacMan_CANOpen.ino located in the PacMan_CANOpen directory in the repository. This should open in the Arduino IDE if installed correctly
6. Connect the ESP32 Dev Board to the computer via the microUSB port
7. Select the proper serial port from the "Tools" drop down and set the baud rate to 115200 (isn't it funny how all the baud rates are multiples of 60 ;) )
8. Click on the compile and upload button (The right-facing arrow on the upper-left of the IDE)
9. Open the Serial Monitor by clicking on the Magnifying glass in the top right corner or going to "Tools" -> "Serial Monitor" after the computer has compiled and uploaded the code

Uploading with a pre-compiled binary

1. Install ESPtool (esptool.py) using pip install esptool
   1. This requires Python which is installed by default on most Linux Distros (including the RaspberryPi), but otherwise can be downloaded and found here
2. Plug in the ESP32 on the PacMan board via it's USB cable
3. Locate it's serial port:
   1. Debian (Ubuntu/Raspbian) Tutorial
   2. Mac OS X Tutorial
   3. Windows Tutorial (First answer)
4. In Terminal / Command Prompt type (excluding bracketed information):
   1. esptool [or esptool.py] --chip esp32 erase_flash
   2. esptool [or esptool.py] --chip esp32 --port [port you found in part 3] write_flash 0x1000 [Latest binary file]
5. Wait for flashing to complete and you should be good to go!

Using the PacMan

The Packs have a user-friendly display that may be used to view data and configure registers for the packs or CANbus. Screens on the display may be navigated through via the button panel found beneath it. A detailed instructional video can be found here.

Connecting up the PacMan

Detailed instructions for this are located in the TSV User-Manual since this ties heavily with the overall assembly of the pack.

Process Diagram

Key:

• Blue: Core 1 running code
• Purple: Core 0 running code

Notes & Further Documentation

• You can expand the documentation here by using the Doxygen documentation included in our code. A tutorial can be found here. You should have Doxygen installed on your system beforehand. This can easily be done on Debian linux based systems like Raspbian on the RaspberryPi by entering the following commands into the Terminal:

  • sudo apt-get update -y

  • sudo apt-get install -y doxygen

• Setting the #define DEBUG in our code to true will allow more serial output to be displayed to the user for debugging purposes to see the state of the PacMan more clearly
• A tutorial on how to setup a RaspberryPi from scratch can be found here. Note that to get internet you will have to register the device (if it has fallen out of registration from our accounts) on Lafayette's network like you do on your laptop or desktop. IP addresses can often change on Lafayette's network so it is recommended to setup the Pi on a monitor and keyboard and mouse and then setup the RaspberryPi to email it's IP upon boot-up (Note: add a delay into this code to allow the RaspberryPi to connect to WiFi first or it could easily fail).
  • A pre-built image including the repository and the Arduino IDE can be found here, including the drivers needed for the CAN hat. You can use this to easily compile and upload the code onto the PacMan. This image will not have the IP script.

Useful Documents

• PacMan Board Repository with Schematic and Board Layout
  • Requires the FSAE KiCAD libraries for proper viewing.
• Usable ESP32 Pins
• Brief overview of CANopen
• Brief overview of I2C

Authors - Feel free to email us questions about our parts!

• Clement Hathaway - Communication, Safety, and Documentation
• Simone Khalifa - Display, Interface, and Documentation
• Dwayne Whittaker - Communication and Safety

Other Useful Links

• A tutorial for writing and using Libraries (similar to classes) in Arduino
• Custom building in the Atom IDE
• Arduino Command Line Interface (CLI) to use with the custom building
• Tips on using Git and Github within Atom
• Our CAN interface hat for the RaspberryPi
  • A tutorial for setup on Raspbian (debian)