SVEA Low Level Interface (LLI)

This repository contains firmware for the SVEA Powerboard 2. PlatformIO is used to build and upload the firmware. Instructions and scripts for installing PlatformIO together with other dependencies are included in this repository. See the Setup section for further instructions.

Readme Structure

Repository structure

Structure of the repository
Setup

Instructions for seting up the software required to flash the board.
Usage

How to flash the board, and use the different targets.
Features

An overview of the features in the firmware.
ROS Related

Published and subscribed topics, and how they should be interpreted.

Repository structure

Source code location

This folder contains the source code for the firmware
Libraries

Contains libraries
Build scripts and other utilities
PlatformIO configurations
Developer instructions

Setup

There are three options for how to install platformIO. The two first options will create a virtual environment for PlatformIO. The last option will install the PlatformIO library directly with your other python libraries.

For development with Visual Code

Recommended for development

git clone this repository to a folder on your computer
[If a conda environemnt is acitve] Deactivate any active conda environment with conda deactivate
Install the platformIO plugin for VS Code as described in https://platformio.org/install/ide?install=vscode
Go to the root folder of this repository and run bash init.sh
Open the reository folder in VS Code

Command line only

Recommended for just flashing new firmware

git clone this repository to a folder on your computer
[If a conda environemnt is acitve] Deactivate any active conda environment with conda deactivate
Install PlatformIO by executing: python3 -c "$(curl -fsSL https://raw.githubusercontent.com/platformio/platformio/master/scripts/get-platformio.py)"
Go to the root folder of this repository and run bash init.sh

I'm in a hurry and I just need to flash this Powerboard NOW

Not recommended unless the previous methods has already failed

git clone this repository to a folder on your computer.
Go to the root folder of this repository and run bash init.sh

Usage

Compile and upload firmware

From command line

Navigate to the root folder of the repository
Actiate the PlatformIO vritual environment with source ~/.platformio/penv/bin/activate
Connect the Powerboard via USB
Execute pio run -t upload

From VS Code

VS Code can be used to build and upload the firmware to the Powerboard if the PlatformIO plugin is installed.

Open the root folder of this repository in VS Code
Go to the PlatformIO tab in VS code
Klick on the Default folder
Open the General tab
Klick on Upload All (Only one environemnt will actually be built and uploaded) The virtual environment will automatically be activated by the PlatformIO plugin.

Available environments

There are 5 different environemnts defined in platformio.ini. The difference between these environemnts is how the rosserial libraries are created. The environment can be set with the -e flag, e. g. -e *environment name*.

use_included_libs

The default environement. Uses the rosserial libraries included in lib/ros_included. This is the environment that runs if no --environment or -e argument is passed to pio run. This environment is can be used if no messages defintions have been added or changed. Note that most of the standard message defitions, like std_msgs, geometry_msgs, and nav_msgs are already included.

build_local_libs

Build the rosserial libraries from the currently sourced ROS workspaces. Rosserial and all required message definitions have to be included in these workspaces, or the compilation will fail. Intended to be used for development where messages have been added or altered on the current machine. The newly built rosserial libraries will be placed in a folder named lib/ros_local. Note: This environment generates rosserial messages, but does not build the workspaces. The workspaces will have to be built manually for any changes to message definitions to take effect.

use_local_libs

Same as use_included_libs but will use rosserial libraries located in lib/ros_local (previously generated by build_local_libs), instead of lib/ros_included.

download_and_build_remote_libs

Download both rosserial and all messages from the vehicle_msgs repository, build them and place the rosserial library in lib/ros_remote. Some temporary ROS workspaces will be placed in a tmp folder in the root of the repository.

use_remote_libs

Same as use_included_libs but will use rosserial libraries located in lib/ros_remote instead (previously generated by download_and_build_remote_libs), instead of lib/ros_included.

Features

This is a summary of the features that are implemented in the firmware. Some features that are not implemnted, but is supported by the hardware are also listed under Not Implemented.

PWM reading

Up to five pwm signals from a receiver can be read and translated to acuation values.
PWM actuation

PWM signals can be sent to steering, velocity, gear, and differential locks.
ROS connection

The firmware can communicate with a ROS network over rosserial. See the ROS Related section for details.
On board LEDs

The four on board LEDs can be controlled by the Teensy. Currently the colors represent:
1. Green/Red: ROS is active/idle
2. Green/Red: The remote is connected/disconnected
3. Green/Red: Remote override is on/off
4. Green/Red: Emergency break on/off
If the remote is disconnected and ROS is inactive the LED will go into disco mode.
Servo Power off on idle

Power to the servos will be cut if the remote is disconnected, and nothing is being sent through ROS.
Emergency Breaking

An emergency break can be initiated trough ROS. All other actuation will be ignored until the emergency is cleared.
Steering calibration

The steering can be calibrated with the remote. Initiate callibration by holding down button 0 for 1 second. The LEDs should turn yellow. Now turn the tires as far to the left as they can go without pushing against the chassis. Push button 0 again. The LEDs should turn blue. Turn the tire as far to the right as they can go without pushing against the chassis. Push button 0 again and the LEDs should blink for a short while. The callibration is complet and the values have been saved to flash.

Not Implemented

External LEDs

External LED connectors are available on the SPMB2, however these are currently not supported by the firmware.
Power measurements through INA260

There is a INA260 power sensor on the SPMB2 that can be used to measure the power consumed by the powerboard (excluding servos). The INA260 is connected to I2C1 on the Teensy.

ROS Related

The following topics are subscribed to and published on by the firmware.

Subscribed Topics

lli/actuation_request ([svea_msgs/lli_actuation.msg])

Takes request for an actuation to be set.

If nothing is published for SW_TIMEOUT milli seconds, the ROS actuation will be considered idle. If the remote is not activem the acuation will go idle, otherwise control will be handed over to the remote.

Values of -128 are treated as do not change i.e. whichever value that was previously actuated will continue to be actuated.

The ctrl field has no effect except that it can be used to trigger a response on lli/actuated by changing the flags instead of the actuation values.
lli/emergency ([svea_msgs/lli_emergency.msg])

Emergency brake which will override other actuation requests. If the value of the message is True, the vehicle will break and ignore any further input until either:
- A message with False is sent
- A time defined by EMERGENCY_T_CLEAR_LIMIT has passed and the remote is in the override position.

Published Topics

lli/actuated ([svea_msgs/lli_actuation.msg])

The currently actuated values will be published here, independent of source. Values will only be published if there is a change. No new message will be published if an actuation value is received that is identical (same stering, velocity, gear, differential locks, and control flags) to the one already being actuated.

The first four bits in the ctrl value represents 0. ROS is considered idle
1. The remote is considered idle
2. The remote override is turned on
3. An emergency has been set
lli/remote ([svea_msgs/lli_actuation.msg])

Readings from the remote. The control flags are the same as for lli/actuated.
lli/encoder ([svea_msgs/lli_encoder.msg])

Encoder tics and time intervals for each wheel if encoders are mounted. If no encoders are mounted, zeero readings will still be published.

FAQ

The ROS header file cannot be found.

Ensure that you ran init.sh (required to use automated hooks) and that you restarted your login session. (reboot or re-login) You can test if echo ${tmw_DIR} outputs the directory of your teensy_firmware clone.

Also ensure that you have a catkin compatible Python version. (Note that Python 3.7 has a trollius and async issue. Easiest is to switch your virtualenvironment to Python2 and install the dependencies with pip install -r requirements.txt. Also ensure that after the virtual environment switch you should execute source /opt/ros/${ROS_DISTRO}/setup.{sh,zsh}).

The build fails and throws some error.

Inspect the logs generated by the hooks under ./firmware/log/middleware.log

The output could look similar to the following snippet.

(vp2) firmware cat log/middleware.log
Input arguments received:
	 template git clone https://github.com/prothen/testbed_msgs.git
Set project name: template
Parse repository:
	 git clone https://github.com/prothen/testbed_msgs.git
Received additional libraries.
ROS1 interface chosen. Configuring dependencies ... (tzz its 2021...)
BUILD rosserial arduino from upstream:
remote: Enumerating objects: 467, done.
remote: Counting objects: 100% (467/467), done.
remote: Compressing objects: 100% (351/351), done.
remote: Total 467 (delta 115), reused 297 (delta 60), pack-reused 0
Receiving objects: 100% (467/467), 299.88 KiB | 3.57 MiB/s, done.
Resolving deltas: 100% (115/115), done.
----------------------------------------------------------------

Contribution

Any contribution is welcome. If you find missing instructions or something did not work as expected please create an issue and let me know.

License

See the LICENSE file for details of the available open source licensing.

tbolin/svea_lli_firmware