search

libhal / SJSU-Dev2

Firmware platform written by San Jose State University for building application for embedded systems
Apache License 2.0
42 stars 63 forks source link

readme

SJSU-Dev2

Discord Github Actions codecov Documentation Status Codacy Badge GitHub stars GitHub forks GitHub issues

Cross platform firmware framework written by students, alumni, and faculty of San Jose State University. Designed for the original purpose of helping students develop firmware for the SJTwo board.

šŸ—ļø WARNING: UNDER HEAVY CONSTRUCTION šŸš§

Currently Ongoing Breaking Changes:

  1. New common API for modules
  2. Introduction of Docker Images and Containers to make development consistent across computer operating systems.
  3. Renaming and reorganization of the library folder

Additional Considered Changes:

  1. New build system (maybe meson, or CMake (ick), or our own custom build system called cpp-build)
  2. Add package management system to separate platform and peripheral implementation details from main codebase.

šŸ“– Full Documentation & Guides

āš™ļø Software APIs

šŸ’» Operating System Supported

šŸš€ Quick Start

To download and setup the environment, simply copy and paste this into a terminal:

git clone https://github.com/SJSU-Dev2/SJSU-Dev2.git
cd SJSU-Dev2
./setup

asciicast

If you find that git is not installed on your machine follow these steps to install GIT.

šŸ› ļø Building a Project

A good project to start with would be the hello_world project. It can be found in the projects/ folder. The example projects can be found in the demos/ folder.

Building hello_world:

cd project/hello_world
make application

šŸ“„ Programming a Device

From within a project, run

make flash

asciicast

Most platforms do not have make flash available, and in those cases JTAG/SWD can be used to program a device. Hook up a JTAG or SWD to your MCU and execute the following command with the correct JTAG and PLATFORM selected:

make program JTAG=<jlink|stlink|etc> PLATFORM=<stm32f10x|lpc17xx|etc>

Example using a STLink to program a stm32f10x

make program JTAG=stlink PLATFORM=stm32f10x

šŸ–„ļø Viewing Serial Output

The preferred method for communicating with a serial devices is via Google Chrome, using the online serial terminal tool, Telemetry. You can also open this up on your browser using the make telemetry command in a project directory.

šŸ”Ž Debugging Device

If you are using a JTAG or SWD device with your MCU, you can debug the device with a similiar command to programming:

make debug JTAG=<jlink|stlink|etc> PLATFORM=<stm32f10x|lpc17xx|etc>

Example using a STLink to program a stm32f10x:

make debug JTAG=stlink PLATFORM=stm32f10x

STDOUT and STDIN will be available via the gdb debug monitor.

šŸ“¦ Windows Users: Using a Virtual Machine

One of the easiest ways to get started with SJSU-Dev2 for Windows users is to use a prebuilt virtual machine.

Steps to install virtual box and the virtual machine are listed below:

  1. Download and install Virtualbox and then the "VirtualBox Oracle VM VirtualBox Extension Pack" on your computer from this link: VirtualBox Download
  2. Download a prebuilt VirtualBox image for Ubuntu from https://www.osboxes.org/ubuntu/. If you don't know which version to choose, use 18.04.3.
  3. Open the file with VirtualBox to setup and open the virtual machine.

Setting up SJSU-Dev2

Now that the VM is up and running, you can use the quick start guide to download and setup SJSU-Dev2.

Connecting USB Devices to Virtual Machine

  1. Open the Ubuntu Virtual Machine on the left hand side.
  2. Login by entering the password "osboxes.org"
  3. To program and interact with your board, you will need to connect it to your host machine and bring it into the virtual machine by using the top menu: Devices > USB > CP2102n...
  4. At this point you can run commands like make application and make flash from within the SJSU-Dev2 folder.

šŸŒŒ Future Goals of SJSU-Dev2