ardupilot/libraries/AP_Camera/AP_RunCam.h

444 lines
15 KiB
C++

/*
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
/*
implementation of RunCam camera protocols
With thanks to betaflight for a great reference
implementation. Several of the functions below are based on
betaflight equivalent functions
*/
#pragma once
#include <AP_HAL/AP_HAL.h>
#include <AP_Vehicle/AP_Vehicle_Type.h>
#ifndef HAL_RUNCAM_ENABLED
#define HAL_RUNCAM_ENABLED !HAL_MINIMIZE_FEATURES
#endif
#if HAL_RUNCAM_ENABLED
#include <AP_Param/AP_Param.h>
#include <RC_Channel/RC_Channel.h>
#include <AP_RCMapper/AP_RCMapper.h>
#include <AP_Arming/AP_Arming.h>
#include <AP_OSD/AP_OSD.h>
#define RUNCAM_MAX_PACKET_SIZE 64
#define RUNCAM_DEFAULT_BUTTON_PRESS_DELAY 300
// 5-key OSD auto-repeats if pressed for too long
#define RUNCAM_5KEY_BUTTON_PRESS_DELAY 100
/// @class AP_RunCam
/// @brief Object managing a RunCam device
class AP_RunCam
{
public:
AP_RunCam();
// do not allow copies
CLASS_NO_COPY(AP_RunCam);
// get singleton instance
static AP_RunCam *get_singleton() {
return _singleton;
}
enum class DeviceType {
Disabled = 0,
SplitMicro = 1, // video support only
Split = 2, // camera and video support
Split4k = 3, // video support only + 5key OSD
Hybrid = 4, // video support + QR mode switch
};
// operation of camera button simulation
enum class ControlOperation {
RCDEVICE_PROTOCOL_SIMULATE_WIFI_BTN = 0x00, // WiFi/Mode button
RCDEVICE_PROTOCOL_SIMULATE_POWER_BTN = 0x01,
RCDEVICE_PROTOCOL_CHANGE_MODE = 0x02,
RCDEVICE_PROTOCOL_CHANGE_START_RECORDING = 0x03,
RCDEVICE_PROTOCOL_CHANGE_STOP_RECORDING = 0x04,
UNKNOWN_CAMERA_OPERATION = 0xFF
};
// control for OSD menu entry
enum class ControlOption {
STICK_YAW_RIGHT = (1 << 0),
STICK_ROLL_RIGHT = (1 << 1),
THREE_POS_SWITCH = (1 << 2),
TWO_POS_SWITCH = (1 << 3),
VIDEO_RECORDING_AT_BOOT = (1 << 4)
};
// initialize the RunCam driver
void init();
// camera button simulation
bool simulate_camera_button(const ControlOperation operation, const uint32_t transition_timeout = RUNCAM_DEFAULT_BUTTON_PRESS_DELAY);
// start the video
void start_recording();
// stop the video
void stop_recording();
// enter the OSD menu
void enter_osd();
// exit the OSD menu
void exit_osd();
// OSD control determined by camera options
void osd_option();
// update loop
void update();
// Check whether arming is allowed
bool pre_arm_check(char *failure_msg, const uint8_t failure_msg_len) const;
static const struct AP_Param::GroupInfo var_info[];
private:
// definitions prefixed with RCDEVICE taken from https://support.runcam.com/hc/en-us/articles/360014537794-RunCam-Device-Protocol
// possible supported features
// RunCam Split 3S micro reports 0x77 (POWER, WIFI, MODE, SETTING, DPORT, START)
// RunCam Split 2S reports 0x57 (POWER, WIFI, MODE, SETTING, START)
// RunCam Racer 3 reports 0x08 (OSD)
enum class Feature {
RCDEVICE_PROTOCOL_FEATURE_SIMULATE_POWER_BUTTON = (1 << 0),
RCDEVICE_PROTOCOL_FEATURE_SIMULATE_WIFI_BUTTON = (1 << 1), // WiFi/Mode button
RCDEVICE_PROTOCOL_FEATURE_CHANGE_MODE = (1 << 2),
RCDEVICE_PROTOCOL_FEATURE_SIMULATE_5_KEY_OSD_CABLE = (1 << 3),
RCDEVICE_PROTOCOL_FEATURE_DEVICE_SETTINGS_ACCESS = (1 << 4),
RCDEVICE_PROTOCOL_FEATURE_DISPLAY_PORT = (1 << 5),
RCDEVICE_PROTOCOL_FEATURE_START_RECORDING = (1 << 6),
RCDEVICE_PROTOCOL_FEATURE_STOP_RECORDING = (1 << 7),
FEATURES_OVERRIDE = (1 << 14)
};
const uint16_t RCDEVICE_PROTOCOL_FEATURE_2_KEY_OSD =
uint16_t(Feature::RCDEVICE_PROTOCOL_FEATURE_CHANGE_MODE)
| uint16_t(Feature::RCDEVICE_PROTOCOL_FEATURE_SIMULATE_WIFI_BUTTON)
| uint16_t(Feature::RCDEVICE_PROTOCOL_FEATURE_SIMULATE_POWER_BUTTON);
// camera control commands
enum class Command {
RCDEVICE_PROTOCOL_COMMAND_GET_DEVICE_INFO = 0x00,
RCDEVICE_PROTOCOL_COMMAND_CAMERA_CONTROL = 0x01,
RCDEVICE_PROTOCOL_COMMAND_5KEY_SIMULATION_PRESS = 0x02,
RCDEVICE_PROTOCOL_COMMAND_5KEY_SIMULATION_RELEASE = 0x03,
RCDEVICE_PROTOCOL_COMMAND_5KEY_CONNECTION = 0x04,
COMMAND_NONE
};
// operation of RC5KEY_CONNECTION
enum class ConnectionOperation {
RCDEVICE_PROTOCOL_5KEY_FUNCTION_OPEN = 0x01,
RCDEVICE_PROTOCOL_5KEY_FUNCTION_CLOSE = 0x02
};
// operation of 5 Key OSD cable simulation
enum class SimulationOperation {
SIMULATION_NONE = 0x00,
RCDEVICE_PROTOCOL_5KEY_SIMULATION_SET = 0x01,
RCDEVICE_PROTOCOL_5KEY_SIMULATION_LEFT = 0x02,
RCDEVICE_PROTOCOL_5KEY_SIMULATION_RIGHT = 0x03,
RCDEVICE_PROTOCOL_5KEY_SIMULATION_UP = 0x04,
RCDEVICE_PROTOCOL_5KEY_SIMULATION_DOWN = 0x05
};
// protocol versions, only version 1.0 is supported
enum class ProtocolVersion {
RCSPLIT_VERSION = 0x00, // unsupported firmware version <= 1.1.0
VERSION_1_0 = 0x01,
UNKNOWN
};
// status of command
enum class RequestStatus {
NONE,
PENDING,
SUCCESS,
INCORRECT_CRC,
TIMEOUT
};
enum class State {
INITIALIZING, // uart open
INITIALIZED, // features received
READY,
VIDEO_RECORDING,
ENTERING_MENU,
IN_MENU,
EXITING_MENU
};
enum class Event {
NONE,
ENTER_MENU,
EXIT_MENU,
IN_MENU_ENTER,
IN_MENU_RIGHT, // only used by the 5-key process
IN_MENU_UP,
IN_MENU_DOWN,
IN_MENU_EXIT,
BUTTON_RELEASE,
STOP_RECORDING,
START_RECORDING
};
enum class OSDOption {
NONE,
ENTER,
EXIT,
OPTION,
NO_OPTION
};
enum class VideoOption {
NOT_RECORDING = 0,
RECORDING = 1
};
enum class ButtonState {
NONE,
PRESSED,
RELEASED
};
static const uint8_t RUNCAM_NUM_SUB_MENUS = 5;
static const uint8_t RUNCAM_NUM_EXPECTED_RESPONSES = 4;
static const uint8_t RUNCAM_MAX_MENUS = 1;
static const uint8_t RUNCAM_MAX_MENU_LENGTH = 6;
static const uint8_t RUNCAM_MAX_DEVICE_TYPES = 4;
// supported features, usually probed from the device
AP_Int16 _features;
// delay time to make sure the camera is fully booted
AP_Int32 _boot_delay_ms;
// delay time to make sure a button press has been activated
AP_Int32 _button_delay_ms;
// delay time to make sure a mode change has been activated
AP_Int32 _mode_delay_ms;
// runcam type/firmware revision
AP_Int8 _cam_type;
// runcam control options
AP_Int8 _cam_control_option;
// video on/off
VideoOption _video_recording = VideoOption::NOT_RECORDING;
// detected protocol version
ProtocolVersion _protocol_version = ProtocolVersion::UNKNOWN;
// uart for the device
AP_HAL::UARTDriver *uart;
// camera state
State _state = State::INITIALIZING;
// time since last OSD cycle
uint32_t _last_osd_update_ms;
// start time of the current button press or boot sequence
uint32_t _transition_start_ms;
// timeout of the current button press or boot sequence
uint32_t _transition_timeout_ms;
// record last state transition to avoid spurious transitions
Event _last_rc_event;
State _last_state = State::INITIALIZING;
OSDOption _last_osd_option = OSDOption::NONE;
int8_t _last_in_menu;
VideoOption _last_video_recording = VideoOption::NOT_RECORDING;
// OSD state machine: button has been pressed
ButtonState _button_pressed = ButtonState::NONE;
// OSD state machine: waiting for a response
bool _waiting_device_response;
// OSD option from RC switches
OSDOption _osd_option;
// OSD state mechine: in the menu, value indicates depth
int8_t _in_menu;
// the starting value of _in_menu
int8_t _menu_enter_level;
// OSD state machine: current selection in the top menu
int8_t _top_menu_pos;
// OSD state machine: current selection in the sub menu
uint8_t _sub_menu_pos;
// lengths of the sub-menus
static uint8_t _sub_menu_lengths[RUNCAM_NUM_SUB_MENUS];
// shared inbound scratch space
uint8_t _recv_buf[RUNCAM_MAX_PACKET_SIZE]; // all the response contexts use same recv buffer
class Request;
FUNCTOR_TYPEDEF(parse_func_t, void, const Request&);
// class to represent a request
class Request
{
friend class AP_RunCam;
public:
Request(AP_RunCam *device, Command commandID, uint8_t param,
uint32_t timeout, uint16_t maxRetryTimes, parse_func_t parserFunc);
Request() { _command = Command::COMMAND_NONE; }
uint8_t *_recv_buf; // response data buffer
AP_RunCam *_device; // parent device
Command _command; // command for which a response is expected
uint8_t _param; // parameter data, the protocol can take more but we never use it
private:
uint8_t _recv_response_length; // length of the data received
uint8_t _expected_response_length; // total length of response data wanted
uint32_t _timeout_ms; // how long to wait before giving up
uint32_t _request_timestamp_ms; // when the request was sent, if it's zero keep waiting for the response
uint16_t _max_retry_times; // number of times to resend the request
parse_func_t _parser_func; // function to parse the response
RequestStatus _result; // whether we were successful or not
// get the length of the expected response
uint8_t get_expected_response_length(const Command command) const;
// calculate a crc
uint8_t get_crc() const;
// parse the response
void parse_response() {
if (_parser_func != nullptr) {
_parser_func(*this);
}
}
struct Length {
Command command;
uint8_t reponse_length;
};
static Length _expected_responses_length[RUNCAM_NUM_EXPECTED_RESPONSES];
} _pending_request;
// menu structure of the runcam device
struct Menu {
uint8_t _top_menu_length;
uint8_t _sub_menu_lengths[RUNCAM_MAX_MENU_LENGTH];
};
static Menu _menus[RUNCAM_MAX_DEVICE_TYPES];
// return the length of the top menu
uint8_t get_top_menu_length() const {
return _menus[_cam_type - 1]._top_menu_length;
}
// return the length of a particular sub-menu
uint8_t get_sub_menu_length(uint8_t submenu) const {
return _menus[_cam_type - 1]._sub_menu_lengths[submenu];
}
// disable the OSD display
void disable_osd() {
#if OSD_ENABLED
AP_OSD* osd = AP::osd();
if (osd != nullptr) {
osd->disable();
}
#endif
}
// enable the OSD display
void enable_osd() {
#if OSD_ENABLED
AP_OSD* osd = AP::osd();
if (osd != nullptr) {
osd->enable();
}
#endif
}
// OSD update loop
void update_osd();
// update the state machine when armed or flying
void update_state_machine_armed();
// update the state machine when disarmed
void update_state_machine_disarmed();
// handle the initialized state
void handle_initialized(Event ev);
// handle the ready state
void handle_ready(Event ev);
// handle the recording state
void handle_recording(Event ev);
// run the 2-key OSD simulation process
void handle_in_menu(Event ev);
// map rc input to an event
AP_RunCam::Event map_rc_input_to_event() const;
// run the 2-key OSD simulation process
void handle_2_key_simulation_process(Event ev);
// eexit the 2 key OSD menu
void exit_2_key_osd_menu();
// run the 5-key OSD simulation process
void handle_5_key_simulation_process(Event ev);
// handle a response
void handle_5_key_simulation_response(const Request& request);
// commands to start and stop recording
ControlOperation start_recording_command() const;
ControlOperation stop_recording_command() const;
// process a response from the serial port
void receive();
// empty the receive side of the serial port
void drain();
// start the uart with appropriate settings
void start_uart();
// get the RunCam device information
void get_device_info();
// 5 key osd cable simulation
SimulationOperation map_key_to_protocol_operation(const Event ev) const;
// send an event
void send_5_key_OSD_cable_simulation_event(const Event key, const uint32_t transition_timeout = RUNCAM_5KEY_BUTTON_PRESS_DELAY);
// enter the menu
void open_5_key_OSD_cable_connection(parse_func_t parseFunc);
// exit the menu
void close_5_key_OSD_cable_connection(parse_func_t parseFunc);
// press a button
void simulate_5_key_OSD_cable_button_press(const SimulationOperation operation, parse_func_t parseFunc);
// release a button
void simulate_5_key_OSD_cable_button_release(parse_func_t parseFunc);
// send a RunCam request and register a response to be processed
void send_request_and_waiting_response(Command commandID, uint8_t param, uint32_t timeout,
uint16_t maxRetryTimes, parse_func_t parseFunc);
// send a packet to the serial port
void send_packet(Command command, uint8_t param);
// handle a device info response
void parse_device_info(const Request& request);
// wait for the RunCam device to be fully ready
bool camera_ready() const;
// whether or not the requested feature is supported
bool has_feature(const Feature feature) const { return _features.get() & uint16_t(feature); }
// input mode
bool has_2_key_OSD() const {
return (_features.get() & RCDEVICE_PROTOCOL_FEATURE_2_KEY_OSD) == RCDEVICE_PROTOCOL_FEATURE_2_KEY_OSD;
}
bool has_5_key_OSD() const {
// RunCam Hybrid lies about supporting both 5-key and 2-key
return !has_2_key_OSD() && has_feature(Feature::RCDEVICE_PROTOCOL_FEATURE_SIMULATE_5_KEY_OSD_CABLE);
}
// whether or not we can arm
bool is_arming_prevented() const { return _in_menu > _menu_enter_level; }
// error handler for OSD simulation
void simulation_OSD_cable_failed(const Request& request);
// process pending request, retrying as necessary
bool request_pending(uint32_t now);
static AP_RunCam *_singleton;
};
namespace AP
{
AP_RunCam *runcam();
};
#endif // HAL_RUNCAM_ENABLED