Development

Dev Setup

This section should help you to get your development setup going.

In order to debug and step through the code on hardware you will need the following:

• USB debugger
• ESC with easily accessible pins - this can be any BLHeli_S compatible ESC, the one linked has all needed pins acessible
• Regulated power supply - although this is not strictly needed, it is highly recommended. You should set some reasonable current limit to prevent you from releasing the magic smoke should something go wrong

Software

You will need to have windows with Simplicity Studio installed. Most of the core team develop on a Linux host and have a Windows VM running. You can download virtual machine images of Windows 11 directly from microsoft.

Urls with information about Bluejay/Blheli_s/SimonK technology

https://www.embedded.com/designing-a-mcu-driven-permanent-magnet-bldc-motor-controller-part-1/

https://www.embedded.com/designing-a-mcu-driven-permanent-magnet-bldc-motor-controller-part-2/

https://www.embedded.com/designing-a-mcu-driven-permanent-magnet-bldc-motor-controller-part-3/

https://www.st.com/resource/en/application_note/an1946-sensorless-bldc-motor-control-and-bemf-sampling-methods-with--st7mc-stmicroelectronics.pdf

https://www.mouser.com/pdfDocs/AN13000.pdf

Building from source

The Bluejay source code is turned into a firmware binary using the Keil A51 assembler. This section can be used even if you don't have the full dev environment set up as described in the step above.

Installing dependencies

On debian-based systems:

dpkg --add-architecture i386 
apt-get install -y wget wine wine32 make git

For using the docker toolchain, it is important only 32bit wine is installed using wine wine32 If you only plan on using the makefile, both will be installed by specifying wine only.

Obtaining the toolchain

To obtain the toolchain, download the C51 package from Keil. Run it with wine:

wine c51v960a.exe

This will install the toolchain and uVision. To obtain a license key (which you will need in order to link files above a certain size) you will have to run uVision in order to get your Computer ID.

wine ~/.wine/drive_c/Keil_v5/UV4/UV4.exe

Goto https://www.silabs.com/developers/keil-pk51 to register for a free license.

Retreive PSN from email.

Go to File -> License Management note your Computer ID.

With this information, you can request a license key on the Keil license installation page. In the CID field, you need to enter the Computer ID which uVision showed you in the previous step.

The license ID will be sent to you via E-Mail, once received you paste it into the LIC field, press "Add LIC" and you are done.

Building via Make

make help

Usage examples
================================================================
make all                                 # Build all targets
make LAYOUT=A MCU=H DEADTIME=5 PWM=24    # Build a single target

Building via Docker

For your convenience, a Docker Image is provided that will set up the toolchain. For this to work you need to have completed the step Registering via Wine and your .wine directory has to be copied to the tools directory.

The .wine directory can be deleted from the tools directory after the docker image has been created.

To build the docker image install docker and from the tools directory run:

docker build -t bluejay-build .

A build script is provided, it will build all targets if no further parameters are provided:

./build.sh

or a specific target if you chose to:

./build.sh -l A -m H -d 0 -p 96

If a specific target is chosen, all parameters need to be provided: layout, MCU, deadtime, and PWM.

Building from source with custom defaults

Loading custom default at compile time is supported in v0.21.1. This is useful for flashing multiple identical builds with custom startup power settings etc.

Make a copy of the default settings located at src/Settings/BluejaySettings.asm like so:

cd <your repository folder>
mkdir user
cp -r /src/Settings/ user/

This creates the directory user/Settings where you can edit settings accordingly.

The directory has to be in the cloned repository to be included in the default Docker mount. The user directory is ignored by Git.

Make environment

Run make with SETTINGSDIR=<dir>, i.e:

make LAYOUT=J MCU=H DEADTIME=0 PWM=48 SETTINGSDIR=user/Settings/ for the above directory

Docker environment

Pass the option -c <custom settings dir path> into ./build.sh, for example:

./build.sh -l J -m H -d 0 -p 48 -c user/Settings for the above directory

Hardware setup

Here you can check hw setups we use to develop Bluejay.

LANRC setup

Favourite setup

Source code comments

Types of comments:

• Inline comment - starts at char 35 if possible, prefixed with a single ;

    clr ACAB                       ; Comment comes here and relates to this line only

• Banner comments in header of a file and to describe a section in great detail should have the following format:

;**** **** **** **** **** **** **** **** **** **** **** **** ****
;
; HEADLINE
;
; DESCRIPTION 1
; DESCRIPTION 2
;
;**** **** **** **** **** **** **** **** **** **** **** **** ****

• Headlines should help to quickly scan the code and group it into logical sections - only one line:

;**** **** **** **** **** **** **** **** **** **** **** **** ****
; HEADLINE
;**** **** **** **** **** **** **** **** **** **** **** **** ****

• Label descriptors should be one or multiple lines of comments to describe the label in more detail

; A short description to provide more context to the label
label:
    ....

• Line descriptors should explain what the following line(s) do, it should be aligned with the next line

play_beep_melody_loop:
    ; Read current location at Eep_Pgm_Beep_Melody to Temp4...
    clr  A

Other material

Investigation into porting to SDCC

https://github.com/bird-sanctuary/bluejay/issues/37