BlueRobotics’s Navigator Library
This library serves as the entry point for embedding applications using Python on Blue Robotics’s Navigator.
The Navigator board has the Raspberry Pi HAT form factor, which allows you to easily attach it to a Raspberry Pi 4 board. Then you can unleash the power of Navigator to develop new solutions or interact with your ROV hardware.
The board offers the following capabilities:
Control:
LEDs
PWM (Pulse Width Modulation) with 16 channels
Measurements:
ADC (Analog Digital Converter) entries
Magnetic field
Acceleration
Angular velocity
Temperature
Pressure
Currently, it supports armv7 and aarch64 architectures, which are the official defaults for BlueOS. However, despite using the embedded-hal concept, new ports can be added as long as the platform matches the hardware design and specifications.
For more information, including installation instructions, schematics, and hardware specifications, please check the navigator hardware setup guide.
- class bluerobotics_navigator.AdcChannel
Available ADC channels to read from.
- Ch0 = AdcChannel.Ch0
- Ch1 = AdcChannel.Ch1
- Ch2 = AdcChannel.Ch2
- Ch3 = AdcChannel.Ch3
- class bluerobotics_navigator.AxisData
Board-oriented direction axes (x is forwards, y is right, z is down).
- x
- y
- z
- class bluerobotics_navigator.NavigatorVersion
Navigator version.
- Version1 = NavigatorVersion.Version1
- Version2 = NavigatorVersion.Version2
- class bluerobotics_navigator.Raspberry
Raspberry Pi version.
- Pi4 = Raspberry.Pi4
- Pi5 = Raspberry.Pi5
- class bluerobotics_navigator.UserLed
Onboard user-controllable LEDs.
- Led1 = UserLed.Led1
- Led2 = UserLed.Led2
- Led3 = UserLed.Led3
- bluerobotics_navigator.get_led(select)
Gets the selected onboard LED output state.
- Parameters:
select (
UserLed) – A pin to be selected.- Returns:
The current state. True -> ON, False -> OFF.
- Return type:
bool
Examples
>>> import bluerobotics_navigator as navigator
>>> from bluerobotics_navigator import UserLed
>>> led1_on = navigator.get_led(UserLed.Led1)
- bluerobotics_navigator.init()
Initializes the Navigator module with default settings (not necessary).
Examples
>>> import bluerobotics_navigator as navigator
>>> navigator.init()
- bluerobotics_navigator.read_accel()
Reads the current acceleration values (from the ICM20689 chip’s accelerometer).
- Returns:
Measurements in [m/s²]
- Return type:
Examples
>>> import bluerobotics_navigator as navigator
>>> acceleration = navigator.read_accel()
>>> forward_acc = acceleration.x
- bluerobotics_navigator.read_adc(channel)
Reads a specific ADC channel (from the ADS1115 chip).
- Parameters:
select (
AdcChannel) – An ADC channel to read from.- Returns:
Measurement in [V].
- Return type:
float32
Examples
>>> import bluerobotics_navigator as navigator
>>> from bluerobotics_navigator import AdcChannel
>>> adc1_measurement = navigator.read_adc(AdcChannel.Ch1)
- bluerobotics_navigator.read_adc_all()
No documentation
- bluerobotics_navigator.read_gyro()
Reads the current angular velocity (from the ICM20689 chip’s gyroscope).
- Returns:
Measurements in [rad/s]
- Return type:
Examples
>>> import bluerobotics_navigator as navigator
>>> angular_velocity = navigator.read_gyro()
>>> roll_rate = angular_velocity.x
>>> pitch_rate = angular_velocity.y
>>> yaw_rate = angular_velocity.z
- bluerobotics_navigator.read_leak()
Reads the state of leak detector pin from Navigator.
- Returns:
The current state. True -> Leak detection, False -> No leak.
- Return type:
bool
Examples
>>> import bluerobotics_navigator as navigator
>>> leak_detector = navigator.read_leak()
- bluerobotics_navigator.read_mag()
Reads the local magnetic field strengths (from the onboard Ak09915 magnetometer).
- Returns:
Measurements in [µT]
- Return type:
Examples
>>> import bluerobotics_navigator as navigator
>>> mag_field = navigator.read_mag()
- bluerobotics_navigator.read_pressure()
Reads the current pressure (from the onboard BMP280 chip).
- Returns:
Measurement in [kPa]
- Return type:
float32
Examples
>>> import bluerobotics_navigator as navigator
>>> air_pressure = navigator.read_pressure()
- bluerobotics_navigator.read_temp()
Reads the current temperature (from the onboard BMP280 chip).
- Returns:
Measurement in [˚C]
- Return type:
float32
Examples
>>> import bluerobotics_navigator as navigator
>>> air_temperature = navigator.read_temperature()
- bluerobotics_navigator.self_test()
Runs some tests on available sensors, then returns the result (not necessary).
- Returns:
True if the sensors are responding as expected.
- Return type:
bool
Examples
>>> import bluerobotics_navigator as navigator
>>> sensors_ok = navigator.self_test()
- bluerobotics_navigator.set_led(select, state)
Sets the state of the selected onboard LED.
- Parameters:
select (
UserLed) – A pin to be selected.state (bool) – The desired output state. True -> ON, False -> OFF.
Examples
>>> import bluerobotics_navigator as navigator
>>> from bluerobotics_navigator import UserLed
>>> navigator.set_led(UserLed.Led1, True)
- bluerobotics_navigator.set_led_all(state)
Sets all user LEDs to the desired state ( Blue, Green, and Red ).
- Parameters:
state (bool) – The desired output state. True -> ON, False -> OFF.
Examples
>>> import bluerobotics_navigator as navigator
>>> navigator.set_led_all(True)
- bluerobotics_navigator.set_led_toggle(select)
Toggle the output of the selected LED.
- Parameters:
select (
UserLed) – A pin to be selected.
Examples
>>> import bluerobotics_navigator as navigator
>>> from bluerobotics_navigator import UserLed
>>> navigator.set_led_toggle(UserLed.Led1)
- bluerobotics_navigator.set_navigator_version(version)
Sets the navigator version.
- bluerobotics_navigator.set_neopixel(rgb_array)
Set the color brightnesses of a connected NeoPixel LED array.
- Parameters:
state ([[uint8, uint8, uint8], ...]) –
A 2D array containing RGB values for each LED.
Set the Red, Green, and Blue components independently, with values from 0-255.
Examples
>>> import bluerobotics_navigator as navigator
>>> navigator.set_neopixel([[100,0,0]])
- bluerobotics_navigator.set_neopixel_rgbw(rgb_array)
Set the color brightnesses of a connected NeoPixel LED array.
- Parameters:
state ([[uint8, uint8, uint8, uint8], ...]) –
A 2D array containing RGB values for each LED.
Set the Red, Green, Blue and White components independently, with values from 0-255.
Examples
>>> import bluerobotics_navigator as navigator
>>> navigator.set_neopixel([[100,0,0,128]])
- bluerobotics_navigator.set_pwm_channel_duty_cycle(channel, duty_cycle)
Sets the duty cycle (the proportion of ON time) for the selected PWM channel.
Similar to
set_pwm_channel_value(), this function calculate the OFF counter value to match desired PWM channel’s duty_cyle.Notes
A duty cycle of 1.0 or 0.0 acts like a relay.
Details of counters on IC, check
set_pwm_channel_value().- Parameters:
channel (
PwmChannel) – The channel to be selected for PWM.duty_cycle (f32) – Duty cycle count value (0.0 : 1.0).
Examples
>>> import bluerobotics_navigator as navigator
>>> from bluerobotics_navigator import PwmChannel
>>> navigator.init()
>>> navigator.set_pwm_freq_hz(1000)
>>> navigator.set_pwm_channel_duty_cycle(PwmChannel.Ch1, 0.5)
>>> navigator.set_pwm_enable(True)
- bluerobotics_navigator.set_pwm_channel_value(channel, value)
Sets the duty cycle (the proportion of ON time) for the selected PWM channel.
This sets the PWM channel’s OFF counter, with the ON counter hard-coded to 0.
The output turns ON at the start of each cycle, then turns OFF after the specified count (value), where each full cycle (defined by
set_pwm_freq_hz()) is split into 4096 segments.Notes
A duty cycle of 20% is achieved using a count of 819.
To achieve a specific pulse-duration you need to consider the cycle frequency:
value = 4095 * pulse_duration / cycle_period
As an example, if the frequency is set to 50 Hz (20 ms period) then a 1100 µs pulse-duration can be achieved with a 5.5% duty cycle, which requires a count of 225. Similarly, 1900 µs pulses would be achieved with a count of 389.
- Parameters:
channel (
PwmChannel) – The channel to be selected for PWM.value (u16) – Duty cycle count value (0..4095).
Examples
>>> import bluerobotics_navigator as navigator
>>> from bluerobotics_navigator import PwmChannel
>>> navigator.init()
>>> navigator.set_pwm_freq_hz(1000)
>>> navigator.set_pwm_channel_value(PwmChannel.Ch1, 2000)
>>> navigator.set_pwm_enable(True)
- bluerobotics_navigator.set_pwm_channels_duty_cycle(channels, duty_cycle)
Like
set_pwm_channel_duty_cycle(). This function sets the duty cycle for a list of multiple PWM channels.- Parameters:
channels ([
PwmChannel]) – A list of PWM channels to configure.duty_cycle (f32) – Duty cycle count value (0.0 : 1.0).
Examples
You can use this method like
set_pwm_channel_duty_cycle().>>> navigator.set_pwm_channels_value([PwmChannel.Ch1, PwmChannel.Ch16], 0.5)
- bluerobotics_navigator.set_pwm_channels_duty_cycle_values(channels, duty_cycle_values)
Like
set_pwm_channel_duty_cycle(). This function sets the duty cycle for a list of multiple channels with multiple values.- Parameters:
channels ([
PwmChannel]) – A list of PWM channels to configure.duty_cycle_values (f32) – Duty cycle count value (0.0 : 1.0).
Examples
You can use this method like
set_pwm_channel_duty_cycle().>>> navigator.set_pwm_channels_duty_cycle_values([PwmChannel.Ch1, PwmChannel.Ch5], [0.25, 0.75])
- bluerobotics_navigator.set_pwm_channels_value(channels, value)
Like
set_pwm_channel_value(). This function sets the duty cycle for a list of multiple PWM channels.- Parameters:
channels ([
PwmChannel]) – A list of PWM channels to configure.value (u16) – The desired duty cycle value (0..4095).
Examples
You can use this method like
set_pwm_channel_value().>>> navigator.set_pwm_channels_value([PwmChannel.Ch1, PwmChannel.Ch16], 1000)
- bluerobotics_navigator.set_pwm_channels_values(channels, values)
Like
set_pwm_channel_value(). This function sets the duty cycle for a list of multiple channels with multiple values.- Parameters:
channels ([
PwmChannel]) – A list of PWM channels to configure.values ([u16]) – A corresponding list of duty cycle values.
Examples
You can use this method like
set_pwm_channel_value().>>> navigator.set_pwm_channels_values([PwmChannel.Ch1, PwmChannel.Ch5], [1000, 500])
- bluerobotics_navigator.set_pwm_enable(state)
Enables or disables the PWM chip (PCA9685), using the firmware and OE_pin.
- Parameters:
state (bool) – The desired PWM chip state. True -> ON, False -> OFF.
Examples
Please check
set_pwm_channel_value()>>> navigator.set_pwm_enable(True)
- bluerobotics_navigator.set_pwm_freq_hz(freq)
Sets the PWM frequency of the PCA9685 chip. All channels use the same frequency.
This is a convenience wrapper around
set_pwm_freq_prescale(), which chooses the closest possible pre-scaler to achieve the desired frequency.Notes
Servo motors generally work best with PWM frequencies between 50-200 Hz.
LEDs flicker less in video streams when driven at a frequency multiple of the camera’s framerate (e.g. a 30fps camera stream should have LEDs at 30/60/90/120/… Hz).
- Parameters:
freq (float32) – The desired PWM frequency (24..1526) [Hz].
Examples
>>> import bluerobotics_navigator as navigator
>>> navigator.set_pwm_freq_hz(60)
>>> navigator.set_pwm_channel_value(1, 2000)
>>> navigator.set_pwm_enable(True)
- bluerobotics_navigator.set_raspberry_pi_version(version)
Sets the raspberry pi version.
- bluerobotics_navigator.set_rgb_led_strip_size(size)
Sets the size of the navigator led strip (1 is the default), should be called before init.
Examples
>>> import bluerobotics_navigator as navigator
>>> navigator.set_rgb_led_strip_size(1)
>>> navigator.init()
