Refloat - A new VESC Package

Today I’m announcing Refloat, a new VESC Package.

What is Refloat?

Refloat stands for Float, refactored.

The goals of Refloat are:

  • Refactor and modularize the codebase, so that adding new features, as well as just experimenting, is easy and straightforward.
  • Bring a 100% consistent behavior in every usage aspect, be it riding behavior, configuration, state and runtime values reporting or added features like LED lighting or Flywheel.
  • Facilitate a well-defined development model that anyone can join and contribute to the package, with a maintained upstream and a pull request and code review workflow.

Features of Refloat

Major features in the first Refloat release (copied from the changelog):

  • Separate Mahony KP configuration between package and firmware

    Mahony KP configuration is now separate between the App Config (firmware) and the Refloat Config (package). The App Config KP is now used for “true pitch”, meaning a standard KP of less than 1 is required. (Float used Mahony KP of 0.2, here 0.4 is used, as it seems to work better)

    To make the transition seamless and to ensure no misconfiguration happens, Refloat will set the following values in App Config - IMU if it detects Mahony KP greater than 1 being configured there:

    • Mahony KP: 0.4
    • Mahony KI: 0
    • Accelerometer Confidence Decay: 0.1

    You don’t need to do anything when transitioning from Float package, but you can check the values are as described after installation.

    A new Refloat Config item Accelerometer Confidence Decay has been added to the package, which is used for the Refloat balance filter.

  • Separate Axis KP

    The Mahony KP configuration item is now called Pitch KP and controls only the pitch axis. Two new configuration items are introduced, Roll KP and Yaw KP, which control the roll and yaw axes respectively.

    The Mahony KP can now be configured separately for each IMU axis. This feature improves the way the board handles in turns and in a significant way improves the balance profile.

    Technical explanation: High Mahony KP works very well for balancing, but it is only desirable on the pitch axis. The mellow response of high KP has unwanted effects on the roll axis, because when the board rotates in yaw (when turning), roll becomes pitch. The board leads into a turn angled in roll (more pronounced on roundier tires), and this angle translates into pitch and lingers there for an amount of time determined by the KP, causing the nose to be down for a time, until it balances back up.

    Lower roll KP makes the nose hold up better in turns. It makes the board more stable and “stiffer”, especially in short carves. This means the Turn Tilt feature may be less needed and may respond more aggresively.

    The Yaw KP parameter seems to have very little effect on anything, it is included for completeness and experimentation for now. It may be removed in the future if it proves to not be useful. Recommended value is inbetween Pitch KP and Roll KP to not make the model unnecessarily imbalanced.

  • Beautiful new full-featured GUI

  • Advanced LED lighting control

    LED lighting control for front/rear/status strips with configurable animations and smooth transitions.

    Runs in its own thread (meaning it won’t disrupt the control loop) at 30 FPS. Consumes about 1% CPU.


GUI Screenshot:

The package is now in Beta phase. There are no known issues and it has been running reliably for multiple riders, but do be careful.

Download and install

Refloat is in the beta phase now, while it has been extensively tested and is not know to have any serious problems, be cautious.

Download latest release here: Releases · lukash/refloat · GitHub

Install via Packages → Install from file… on mobile, or VESC Packages → Load Custom on desktop.


How can I migrate from existing Float Package to Refloat

Backup your configuration by exporting the XML, install Refloat and load the backup. All options known to Refloat will be loaded, which entails all Float 1.3 options.

Any feedback, especially suggestions for improvement, is very much welcome.


Some of the upcoming planned features:

  • Further work on improving the balancing behavior. The Separate Mahony KPs is still just a bandaid, I’ve got several other ideas to try out and test.
  • Configurable “quick” buttons for: LEDs on/off, Headlights on/off, Flywheel, single sensor / posi, …
  • Configuration management in VESC Tool App UI. It is incredibly cumbersome to just have one set of values in a tune slot. I’m figuring out a flexible system to configure multiple groups of configuration options, like: base tune values, sensor switch configurations (for tricks), pushback configuration,
    LEDs setup, …
  • configurable automatic gyro offset calibration.
  • More LED animations and transitions (there’s just a really basic set right now).
  • From a developer standpoint:
    • Further refactoring.
    • Attempt to standardise the package command protocol so that multiple packages and multiple client apps can interact together in a consistent manner.
    • Attempt to use Protobuffers as the command protocol payload.

Here’s a separate thread for feedback on the Separate KP feature: Refloat Separate KP Feedback

Regarding the support for LCM (Floatwheel and others): It has been ported from Float and is untested, as I don’t own a Floatwheel. I’m looking for someone to test it. Anyone with an LCM flashed with the new FW that works with Float, please report back (or get in touch in case you’d be willing to troubleshoot issues with me).

What should work with an LCM is controlling the brightness using the LEDs on/off and headlights on/off toggles, and the brightness configuration for the LCM as described in the LED Type configuration option.

On a Floatwheel, there should be an indicator when the charger is connected, and it should show the charger voltage and current.

Looks great, worked out of the box on my Thor board, even restore from Float package settings works seamlessly - can you post instructions on how to configure Thor lights?

1 Like

There’s nothing too special, you just select LED Pin B7 (I think I should rename the values to something that’s more accessible). The rest of the options is very similar to Float (except I also have options to reverse the strip direction). The hardware-related LED settings are in the Specs tab.

Then, to set up the colors etc. on the LEDs, you’ll have to go through the options in the LEDs tab… Ideally I’d make a video on how to set that up. Not sure I’m gonna get to it anytime soon though. It’s not really that complicated, but I understand it’s a bit overwhelming and not well presented by the VESC Tool config interface. Note there are several groups of identical options for Front, Rear, Headlights, Taillights and Status Idle.

If there’s something that’s not clear in the options help text or the Readme, let me know, I’ll amend it.

I was chatting for a while with Fajdiga yesterday, he got the LEDs working on Fungineers hardware. If you have a status bar too, there are several bugs related to the status bar Fajdiga reported and I have them fixed, just need to make another release. I don’t have a status bar myself (yet), so I can’t really test it too well.

for LEDs the config restore from float v2.0 did not work for me - my LEDs are now stuck permanently on (instead of knight rider, as shown in refloat cfg), also LED type is set to “NONE” yet still the LEDs are on, shouldn’t they be permanently off?

I assume you did restart the board? If yes, sounds not possible though. You know how VESC config works… there’s nothing special in the code, just for the LED setup you need to reboot the board (and when you restart the lisp package, the LEDs will stay at whatever color they were when the control signal stopped, if they aren’t configured properly at the point the package starts).

(And as I said, it’s been working for Fajdiga and it’s working for me…)

I can confirm, once I set LED type to RGB instead of None it behaves as expected. Have you or Fajdiga tried type NONE? So basically two issues: type=RGB somehow didn’t get carried over for me, and for type=NONE I expected LEDs to be disabled/off. But the latter may be a Thor issue rather than a Package issue?

You may need to write out the exact sequence for me, including config writes, board reboots and potentially package loading if you’re doing that.

If you have LEDs working and being lit up, setting LED type None will not turn them off immediately. Again, restart is reboot is required. After a board reboot, they definitely can’t be on, as the whole LED code is disabled (unless there’s some noise on the data pin during the boot sequence, I have a bit of that on my board that lights up the first LED green often when I turn the board on). I just retested this and it works, as in:

  1. set LED type to None
  2. write config (LEDs are still on)
  3. reboot board
  4. LEDs don’t light up

My steps are the same as yours, except LEDs turn on as soon as boot finishes. Considering your results I strongly suspects it’s either the Thor controller hardware/firmware or the prototype LED strip Fungineers gave me.

Let’s see what Fajdiga gets with LED-Type=NONE.

Should the Mahony KP in the App config be readjusted to the values from the original float package? I saw that Mahony KP is at .4 but before I had it at 1.8 in app config. Should I change it back?

Huh, really weird. What do they light up to and do they stay that way?

I’ve had that once when I was testing an Aliexpress buck, it’d seem to generate a signal that was recognized by the LEDs and they would light up somewhat erratically… That’s the only idea I have right now. But if it’s working for you in Float, it shouldn’t be a HW issue? I’m quite stumped right now.

0.4 is correct, it’s described in the Readme. Don’t change it to 1.8 :slight_smile:

I had someone test the Floatwheel/LCM control but after setting “Type=External” they did see the lights control button in the AppUI but weren’t able to control the lights.

I’ll get my own Floatwheel back Friday so I can try it out as well, but judging by the code you seemed to have removed in the LCM_Light Control function it probably needs that code re-added.

Yeah, that code is untested, as I don’t own a Floatwheel. But I tried to keep all the code, I just moved it. This might be a bit difficult for me to fix… I might try to hijack a friend’s floatwheel for some time to debug it… If he’ll allow it :slight_smile:

Another thing that should work on a Floatwheel is the charging indicator, I ported that as well. I tested the displaying part, but again couldn’t test the command part.

I’ve released a new beta version: Release Refloat 1.0.0-beta3 · lukash/refloat · GitHub

It only contains a handful of fixes for status LED bar and nothing more, if you don’t have that, there’s no reason to upgrade.

This release will reset your config, so a backup and restore is needed.

You can use the Backup and Restore functionality in App UI → Settings → Setup. It does the same thing as .xml backup, just saves the hassle with saving and loading a file (this will be more automated in the future). Do still back up your .xml though!

What are the steps to migrate from the Float Package to ReFloat? Can I just save settings and then restore them again after installing ReFloat? Or better to start from scratch?

1 Like

You can save and restore. It’s described in the Readme, though I do realize it’s a wall of text :slight_smile:

Where is the readme located? I check the readme in github repo, but did not find that part