syntax="proto3";

package minknow_api.device;

option java_package = "com.nanoporetech.minknow_api";
option objc_class_prefix = "MKAPI";

import "minknow_api/rpc_options.proto";
import "google/protobuf/wrappers.proto";

service DeviceService {
    // Get information about the device this MinKNOW instance was started for.
    //
    // In normal circumstances (ie: when using the manager service), a new MinKNOW instance
    // is started for each available device. This call provides information about this device.
    //
    // The information returned by this call will not change (providing the MinKNOW instance
    // was started by the manager service).
    rpc get_device_info (GetDeviceInfoRequest) returns (GetDeviceInfoResponse) {
        option idempotency_level = NO_SIDE_EFFECTS;
    }

    // Get information about the current device state.
    //
    // Information in this call may change as the device is used with MinKNOW, for example,
    // by unplugging or plugging in the device.
    //
    // It includes information about whether the hardware is actually attached (in the case of
    // MinIONs, which can be unplugged), as well as what types of flow cells can be inserted (which
    // may be affected by flow cell adapters).
    //
    // Since 1.12
    rpc get_device_state (GetDeviceStateRequest) returns (GetDeviceStateResponse) {
        option idempotency_level = NO_SIDE_EFFECTS;
    }

    // Streaming version of get_device_state
    //
    // Since 1.13
    rpc stream_device_state (StreamDeviceStateRequest) returns (stream GetDeviceStateResponse) {
        option idempotency_level = NO_SIDE_EFFECTS;
    }

    // Get information about the flow cell (if any).
    //
    // This provides information about the flow_cell attached to the device (described by
    // get_device_info()), if any.
    rpc get_flow_cell_info (GetFlowCellInfoRequest) returns (GetFlowCellInfoResponse) {
        option idempotency_level = NO_SIDE_EFFECTS;
    }

    // Streaming version of get_flow_cell_info
    //
    // Since 1.13
    rpc stream_flow_cell_info (StreamFlowCellInfoRequest) returns (stream GetFlowCellInfoResponse) {
        option idempotency_level = NO_SIDE_EFFECTS;
    }

    // Set the user specified flow cell id.
    //
    // This changes the user specified flow cell id.
    // MinKNOW will use this id in place of the id read from the eeprom, if no eeprom data
    // is available.
    //
    // This data is reset when the flow cell is disconnected.
    //
    // Since 1.12
    rpc set_user_specified_flow_cell_id (SetUserSpecifiedFlowCellIdRequest) returns (SetUserSpecifiedFlowCellIdResponse) {
        option idempotency_level = IDEMPOTENT;
    }

    // Set the user specified product code.
    //
    // This changes the user specified product code.
    //
    // MinKNOW does not use the product code, it is intended for use in MinKNOW's clients.
    //
    // This data is reset when the flow cell is disconnected.
    //
    // Since 1.12
    rpc set_user_specified_product_code (SetUserSpecifiedProductCodeRequest) returns (SetUserSpecifiedProductCodeResponse) {
        option idempotency_level = IDEMPOTENT;
    }

    // Get information about the channel layout
    //
    // Since 1.14
    rpc get_channels_layout (GetChannelsLayoutRequest) returns (GetChannelsLayoutResponse) {
        option idempotency_level = NO_SIDE_EFFECTS;
    }

    // Reset all settings associate with the current device.
    //
    // This call will initialise all settings to their default state, ie the same as when MinKNOW boots.
    rpc reset_device_settings(ResetDeviceSettingsRequest) returns (ResetDeviceSettingsResponse) {
        option idempotency_level = IDEMPOTENT;
    }

    // Set the calibration measurements to be used by MinKNOW.
    //
    // Calibration describes how to convert from the raw ADC (analog-to-digital converter) values
    // from the device into picoamps (pA).
    //
    // Note that calibration depends on the device, flow cell and some of the device settings
    // (including sampling frequency and the capacitance used in the integration circuit). If
    // any of these are changed, the calibration will no longer be used. Instead, a previously-saved
    // calibration (for that combination of flow cell and settings) might be used, or the identity
    // calibration might be used.
    //
    // On a MinION, the settings that a calibration depends on are sampling frequency and
    // integration capacitor.
    rpc set_calibration (SetCalibrationRequest) returns (SetCalibrationResponse) {
        option idempotency_level = IDEMPOTENT;
    }

    // Clear the current calibration.
    //
    // This is the same as setting the calibration to be the identity function (setting all offsets
    // to 0, and all pA ranges to the digitisation value).
    rpc clear_calibration (ClearCalibrationRequest) returns (ClearCalibrationResponse) {
        option idempotency_level = IDEMPOTENT;
    }

    // The calibration measurements being used by MinKNOW.
    //
    // Calibration describes how to convert from the raw ADC (analog-to-digital converter) values
    // from the device into picoamps (pA).
    //
    // To get a pA value from an ADC value the following function is applied::
    //
    //      pA_current = (adc_current + offset) / (digitisation / pA_range)
    //
    // The digitisation is the range of possible ADC values. It is the same for all channels.
    //
    // If there is no calibration (including if it was cleared with ``clear_calibration()`` or
    // invalidated because of device settings changes), this will return the identity calibration:
    // all offsets will be 0, and the pA ranges will be the same as the digitisation.
    rpc get_calibration (GetCalibrationRequest) returns (GetCalibrationResponse) {
        option idempotency_level = NO_SIDE_EFFECTS;
    }

    // If the device is capable (see GetDeviceInfoResponse.temperature_controllable)
    // then this sets the minimum and maximum temperatures of the flow-cell.
    rpc set_temperature (SetTemperatureRequest) returns (SetTemperatureResponse) {
        option idempotency_level = IDEMPOTENT;
    }

    // Get the current temperature of the device.
    //
    // Since 1.11
    rpc get_temperature (GetTemperatureRequest) returns (GetTemperatureResponse) {
        option idempotency_level = NO_SIDE_EFFECTS;
    }

    // Stream the current temperature of the device.
    //
    // Since 4.3
    rpc stream_temperature (StreamTemperatureRequest) returns (stream GetTemperatureResponse) {
        option idempotency_level = NO_SIDE_EFFECTS;
    }

    // Triggers an unblock for a list of channels for a given duration (Please see UnblockRequest).
    // It will start an unblock for every channel received as a parameter, then this RPC returns.
    // After the timeout expires (the duration in seconds given in the request), the return from
    // unblock is automatically triggered, which resets the channel configuration (mux) to the
    // value preceding the unblock.
    //
    // Notes!!
    //
    // During the unblock the user should NOT do any mux changes, as the unblock will be interrupted.
    // On Promethion this would be even more complicated, as an unblock would normally restore
    // hardware saturation. If an unblock is interrupted it will not restore the state to the original
    // one.
    //
    // The user should NOT change the overload mode during an unblock - this will confuse the return from
    // unblock, which tries to reset the overload mode to the state preceding the unblock.
    //
    // The unblock can fail if the channel is not in a valid well state (this means a channel needs to be
    // in one of pore1-4, not test current, regen pore or unblock). If a mux is not valid, the unblock grpc
    // will try to continue for the rest of the channels, ignoring the one with the wrong mux.
    rpc unblock (UnblockRequest) returns (UnblockResponse) {}

    // Cancel in progress unblocks.
    //
    // Any unblocks registered with `device.unblock` will be stopped before this command returns.
    // Unblocks are stopped by applying any actions required to return from unblock (mux changes, or hardware configuration).
    //
    // Since 1.15
    rpc cancel_unblocks (CancelUnblocksRequest) returns (CancelUnblocksResponse) {}

    // Get the channel configuration for any number of channels
    //
    // The maximum addressable channel will depend on the device. Currently this will be 512 on a MinION/GridION
    // and 3000 on a PromethION
    rpc get_channel_configuration (GetChannelConfigurationRequest) returns (GetChannelConfigurationResponse) {
        option idempotency_level = NO_SIDE_EFFECTS;
    }

    // Set the channel configuration for any number of channels
    //
    // The maximum addressable channel will depend on the device. Currently this will be 512 on a MinION/GridION
    // and 3000 on a PromethION.
    rpc set_channel_configuration (SetChannelConfigurationRequest) returns (SetChannelConfigurationResponse) {
        option idempotency_level = IDEMPOTENT;
    }

    rpc set_channel_configuration_all (SetChannelConfigurationAllRequest) returns (SetChannelConfigurationAllResponse) {
        option idempotency_level = IDEMPOTENT;
    }

    // Set the saturation control configuration.
    //
    // The request is immediately sent to the data acquisition module, and applied. All settings can be changed
    // whilst the experiment is running.
    //
    // If any keys are not specified when this method is called (see the message for specific optional parameters),
    // the previously applied parameters are kept; initially, when this method has never been called, defaults from the
    // application config are used.
    //
    // note: calling this method resets anu in-progress saturations when it is called, causing them to need to start
    // saturation counts again, this may mean any saturations may take longer to occur.
    rpc set_saturation_config(SetSaturationConfigRequest) returns (SetSaturationConfigResponse) {}

    // Get the saturation control configuration.
    //
    // The default configuration is specified by the MinKNOW application configuration, the command returns the most
    // recently applied saturation config.
    rpc get_saturation_config(GetSaturationConfigRequest) returns (GetSaturationConfigResponse) {
        option idempotency_level = NO_SIDE_EFFECTS;
    }

    // Get the sample rate of the device
    //
    // Please refer to MinionDeviceService and PromethionDeviceService for the expected
    // return value for a minion and promethion respectively
    rpc get_sample_rate (GetSampleRateRequest) returns (GetSampleRateResponse) {
        option idempotency_level = NO_SIDE_EFFECTS;
    }

    // Set the sample rate of the device, and returns the actual value set on the device
    //
    // Please refer to MinionDeviceService and PromethionDeviceService to see
    // how the value set here will be used to determine the real sample rate for a
    // minion and promethion respectively
    //
    // Trying to set the sample rate during an acquisition period will result in an error
    rpc set_sample_rate (SetSampleRateRequest) returns (SetSampleRateResponse) {
        option idempotency_level = IDEMPOTENT;
    }

    rpc get_bias_voltage (GetBiasVoltageRequest) returns (GetBiasVoltageResponse) {
        option idempotency_level = NO_SIDE_EFFECTS;
    }

    rpc set_bias_voltage (SetBiasVoltageRequest) returns (SetBiasVoltageResponse) {
        option idempotency_level = IDEMPOTENT;
    }

    // Trigger a device specific dump of device-state control-server log. The
    // information will appear in a "diagnostic_information" message
    //
    // Since 5.0
    rpc dump_state(DumpStateRequest) returns (DumpStateResponse) {
    }
}

// Describes the configuration of a channel on the device.
//
// Note that this is a lossy representation. The device-specific APIs provide more precise
// information. This only describes common configurations, and omits anything that doesn't impact
// the received signal.
message ChannelConfiguration {
    // The currently-connected well.
    //
    // Wells are counted from 1. 0 indicates that no well is connected. 5 indicates some non-generic configuration
    // such as ground for a minion or connecting all wells on promethion
    //
    // Note that MinKNOW can return channel configurations where the well number is larger than the
    // ``max_well_count`` value returned by :meth:`DeviceService.get_device_info`. This indicates
    // that some other connection has been made (for example, PromethIONs can simultaneously
    // connect all wells, and MinIONs can connect to ground).
    uint32 well = 1;

    // Whether the test current is connected to the integrator (measurement circuit).
    //
    // The signal will be a steady test current produced on the device. This can be used for
    // calibration or to test the device integration circuits.
    bool test_current = 2;
}

// Describes the configuration of a channel on the device.
//
// Note that this is a lossy representation. The device-specific APIs provide more precise
// information. This only describes common configurations, and omits anything that doesn't impact
// the received signal.
message ReturnedChannelConfiguration {
    // The currently-connected well.
    //
    // Wells are counted from 1. 0 indicates that no well is connected. 5 indicates some non-generic configuration
    // such as ground for a minion or connecting all wells on promethion
    //
    // Note that MinKNOW can return channel configurations where the well number is larger than the
    // ``max_well_count`` value returned by :meth:`DeviceService.get_device_info`. This indicates
    // that some other connection has been made (for example, PromethIONs can simultaneously
    // connect all wells, and MinIONs can connect to ground).
    uint32 well = 1;

    // Whether the test current is connected to the integrator (measurement circuit).
    //
    // The signal will be a steady test current produced on the device. This can be used for
    // calibration or to test the device integration circuits.
    bool test_current = 2;

    // Whether the unblock voltage is connected to the integrator (measurement circuit).
    //
    // Provides a reverse potential across the connected well. This can be used to drive molecules
    // back out of the well.
    bool unblock = 4;
}

// Describes the type of flow cell connection.
//
// This means that this determines what flow cells can be inserted.
//
// Since 4.1
enum FlowCellConnectorType {
    // This is the default value when this enum is used in requests, and can be used to indicate
    // that the caller doesn't care about flow cell connection types.
    //
    // It should not be returned by any RPCs (if you do see it returned, you may be using
    // minknow_api from 4.1+ to call RPCs on MinKNOW Core 4.0).
    FCCON_NOT_SET = 0;
    // The flow cell position accepts PromethION-style flow cells.
    FCCON_PROMETHION = 1;
    // The flow cell position accepts MinION flow cells. MinION Mk1, Mk1B and Mk1C all accept these
    // flow cells, as well as the GridION X5.
    //
    // Note that if a Flongle adapter is inserted, FCCON_FLONGLE will be returned instead.
    FCCON_MINION_MK1 = 2;
    // The flow cell position accepts Flongle flow cells.
    //
    // Currently, this means a MinION or GridION with a Flongle adapter inserted.
    FCCON_FLONGLE = 3;
}

message GetDeviceInfoRequest {}

message GetDeviceInfoResponse {
    enum DeviceType {
        MINION = 0;
        GRIDION = 2;
        PROMETHION = 3;
        MINION_MK1C = 4;
        TRAXION = 5;
        P2_SOLO = 6;
    }

    // A unique identifier for the device.
    //
    // This is the identifier of the device MinKNOW was started for. It will only communicate
    // with this device.
    //
    // Note that simulated device IDs are only unique for this host, not globally.
    //
    // This value will be set even if the device is not currently connected (assuming MinKNOW
    // was started by the manager service).
    string device_id = 1;

    // The type of the device.
    DeviceType device_type = 2;

    // Whether the device is simulated.
    //
    // If this is true, there is no physical device - MinKNOW is simulating it. If it is false,
    // MinKNOW will be acquiring data from a real device.
    bool is_simulated = 3;

    // The maximum number of channels supported by the device.
    //
    // Each channel provides a signal from the device. For example, a MinION supports up to 512
    // channels, and so can provide 512 simultaneous streams of data.
    //
    // This value is fixed for a given device type. Note, however, that a flow cell might be attached
    // that has a smaller number of channels.
    uint32 max_channel_count = 4;

    // The maximum number of wells connected to each channel.
    //
    // A well is a discrete location on the device where sensing can take place. Normally, each well
    // should have a single nanopore in it.
    //
    // For example, a MinION supports up to 4 wells per channel, allowing for 2048 wells in total.
    // So the value of this for a MinION will be 4.
    //
    // This value is fixed for a given device type. Note, however, that a flow cell might be attached
    // that has a smaller number of wells on each channel.
    uint32 max_wells_per_channel = 5;

    // Whether the set_temperature() method can be expected to work.
    //
    // On some systems, not all connected devices have the ability to control their own temperature,
    // as temperature controls are managed in groups. If this field is true, this device can control
    // its own temperature. If it it false, it cannot, and the temperature will be maintained at a
    // pre-determined temperature.
    bool can_set_temperature = 6;

    // The range of uncalibrated data values.
    //
    // This is the number of distinct signal values that can be produced by the device's analog to
    // digital converter (ADC).
    uint32 digitisation = 7;

    // Firmware versions and serial-numbers of components associated with this device
    //
    // Depending on the hardware, there may be several components associated with
    // this device, each with their own firmware version and serial-number. Not all
    // components have serial-numbers.
    message ComponentVersion {
        // Description of the component that has firmware
        string component = 1;

        // The firmware version, if this cannot be determined for a component where
        // the firmware version would usually be available, this will contain
        // "Unknown"
        string version = 2;

        // The serial-number of a component. If this in not applicable to the
        // type of component or cannot be read at the current time, then this
        // field will be blank.
        string serial_number = 3;
    }
    repeated ComponentVersion firmware_version = 10;
}

message GetDeviceStateRequest {}

message GetDeviceStateResponse {
    enum DeviceState {
        DEVICE_DISCONNECTED = 0;
        DEVICE_READY = 1;
    }

    // Whether the physical hardware is present.
    //
    // This is really only relevant to MinIONs, which could be unplugged by the user at any time.
    DeviceState device_state = 1;

    // Indicates what sort of flow cell can be inserted.
    //
    // For example, if the user needs to set or override the flow cell product code, this can be
    // used to limit the list of possible flow cell product codes to choose from.
    //
    // Since 4.1
    FlowCellConnectorType flow_cell_connector = 2;
}

message StreamDeviceStateRequest {}

message GetFlowCellInfoRequest {}

enum InsertionScriptStatus {
    // An insertion script has not been run for a flow-cell. Not all
    // platforms use an insertion script.
    NOT_RUN = 0;

    // An insertion script has been run and has failed to complete
    // successfully. This can indicate a faulty flow-cell or that the flow-cell
    // has not been inserted correctly.
    FAILED = 1;

    // Script run successfully, hardware ready to use.
    SUCCEEDED = 2;
}

message GetFlowCellInfoResponse {
    // Whether there is a flow cell present.
    //
    // If both this and has_adapter are false, none of the other fields will contain useful
    // information.
    bool has_flow_cell = 1;

    // The number of channels currently supported by the device.
    //
    // This may be smaller than the ``max_channel_count`` value returned by get_device_info(),
    // depending on the attached flow cell.
    uint32 channel_count = 2;

    // The number of wells currently supported by the device.
    //
    // This may be smaller than the ``max_wells_per_channel`` value returned by get_device_info(),
    // depending on the attached flow cell.
    uint32 wells_per_channel = 3;

    // The unique identifier for the flow cell.
    //
    // This should be same as the value printed onto the flow cell casing. Not all flow cells will
    // have the flow cell ID recorded in a way that MinKNOW can read. In those cases, this will be an
    // empty string, even though the user may be able to see a printed identifier on the flow cell.
    string flow_cell_id = 4;

    // The unique identifier for the ASIC (formatted as string).
    //
    // This is a value uniquely identifying the ASIC embedded in the flow cell. It will
    // always be set when a flow cell is present.
    //
    // The intended use for this is to track the identity of the asic in the flow cell, eg. for
    // displaying to users during production of chips.
    //
    // Caveats:
    //
    // * This value will not mean anything to a customer.
    // * There is no guarantee that this field will contain the same identifier across
    //   MinKNOW versions, even with the same flow cell.
    // * An ASIC can be recycled into a new flow cell, so this identifier may be re-used in the
    //   future (although it can be considered unique for the duration of a protocol run).
    string asic_id_str = 13;

    // The product code for the flow cell.
    //
    // This should be the code displayed in the shop where the flow cell was bought. Not all
    // flow cells will have the product code recorded in a way that MinKNOW can read. In those cases,
    // this will be an empty string.
    string product_code = 6;

    // A unique identifier for the flow cell, which the user can specify.
    //
    // In the event a flow cell does not have an eeprom, this field contains data input by the user
    // using set_flow_cell_info to record required data.
    //
    // Only alpha-numeric, space, dash and underscore characters are allowed in this field.
    //
    // Since 1.12
    string user_specified_flow_cell_id = 7;

    // A product code for the flow cell, which the user can specify.
    //
    // This should be the code displayed in the shop where the flow cell was bought. Not all
    // flow cells have an eeprom, in the event they don't, the user can specify using this id using
    // set_flow_cell_info.
    //
    // Since 1.12
    string user_specified_product_code = 8;

    // Whether there is a flongle adapter.
    //
    // If this is true, the adapter_id, channel_count and wells_per_channel fields should all
    // provide useful information, even if has_flow_cell is false.
    bool has_adapter = 9;

    // The unique identifier of an attached flongle adapter.
    //
    // This should be same as the value printed onto the adapter casing.
    string adapter_id = 10;

    // Used to make the field nullable, since the null value is not protobuf's default.
    oneof temperature_offset_nullable {

        // The temperature offset for the flow cell, returned as an offset in degrees Celsius.
        //
        // This offset specifies a correction to be applied to ASIC temperature.
        // If multiple ASIC temperatures are available from the device, applies to the mean temperature.
        //
        // Since 1.14
        float temperature_offset = 11;
    }

    // The version of the ASIC contained in the flow cell (if specified by the hardware).
    //
    // This can be used to determine if the hardware should support certain features
    // added to only newer ASICs.
    //
    // Possible values include: "IA02C", "IA02D", or if the value is not readable on the
    // current hardware an empty string is returned.
    //
    // Since 1.14
    string asic_version = 12;

    // If the configuration specifies a script to run when a flow-cell is inserted,
    // this shows if it completed successfully.
    //
    // Since 5.0
    InsertionScriptStatus insertion_script_status = 14;

}

message StreamFlowCellInfoRequest {}

message SetUserSpecifiedFlowCellIdRequest {
    // A unique identifier for the flow cell, which the user can specify.
    //
    // In the event a flow cell does not have an eeprom, this field can be used by the user
    // to record their flow_cell_id.
    //
    // Since 1.12
    string id = 1 [(rpc_required) = true];
}

message SetUserSpecifiedFlowCellIdResponse {}


message SetUserSpecifiedProductCodeRequest {

    // A product code for the flow cell, which the user can specify.
    //
    // In the event a flow cell does not have an eeprom, the user can specify product code here.
    //
    // Since 1.12
    string code = 1 [(rpc_required) = true];
}

message SetUserSpecifiedProductCodeResponse {}

message GetChannelsLayoutRequest {
}

message GetChannelsLayoutResponse
{
    repeated ChannelRecord channel_records = 1;
}

message ChannelRecord
{
    message MuxRecord
    {
        uint32 id = 1;
        uint32 phys_x = 2;
        uint32 phys_y = 3;
    }
    uint32 id = 1;
    string name = 2;
    repeated MuxRecord mux_records = 3;
}

message ResetDeviceSettingsRequest {}
message ResetDeviceSettingsResponse {}

message SetCalibrationRequest {
    // The first channel included in calibration data.
    //
    // This must always be 1. This is required in order to make sure the client and MinKNOW agree on
    // what data is being provided.
    uint32 first_channel = 1 [(rpc_required) = true];

    // The last channel included in calibration data.
    //
    // This must always be the same as the channel count returned by
    // :meth:`get_flow_cell_info`. This is required in order to make
    // sure the client and MinKNOW agree on what data is being provided.
    uint32 last_channel = 2 [(rpc_required) = true];

    // The ADC value adjustment to reach 0pA on each channel.
    //
    // This is ``-x``, where ``x`` is the (mean) ADC value at 0pA.
    repeated float offsets = 3 [(rpc_required) = true];

    // The range of possible pA values that can be produced by the device.
    repeated float pa_ranges = 4 [(rpc_required) = true];
}

message SetCalibrationResponse {}

message ClearCalibrationRequest {}
message ClearCalibrationResponse {}

message GetCalibrationRequest {
    // The first channel to get calibration data for.
    //
    // This should normally be 1.
    uint32 first_channel = 1 [(rpc_required) = true];

    // The last channel included in calibration data.
    //
    // This should normally be the channel count returned by
    // :meth:`get_flow_cell_info`.
    uint32 last_channel = 2 [(rpc_required) = true];
}

message GetCalibrationResponse{
    // The range of possible ADC values that can be produced by the device.
    //
    // This is the same as the digitisation value returned by the
    // :meth:`DeviceService.get_device_info` RPC. It is included here for convenience.
    uint32 digitisation = 1;

    // The ADC value adjustment to reach 0pA on each channel.
    //
    // This is ``-x``, where ``x`` is the (mean) ADC value at 0pA.
    repeated float offsets = 2;

    // The range of possible pA values that can be produced on each channel.
    //
    // The change in pA represented by a change of 1 ADC can be calculated by dividing the
    // digitisation by this value.
    repeated float pa_ranges = 3;

    // Find if there is a stored calibration, or if the returned response is empty.
    //
    // Since 1.12
    bool has_calibration = 4;
}

message SetTemperatureRequest {
    message WaitForTemperatureSettings {
        // Maximum duration (in seconds) to wait for the device to reach temperature.
        //
        // Not specifying a value will wait for a maximum of 5 minutes.
        uint32 timeout = 1;

        // Minimum duration (in seconds) that the reported temperature must be
        // continually within the target temperature range, before the device is
        // considered to have reached temperature.
        //
        // A value of zero means that the device will be considered to have reached temperature
        // as soon as the reported temperature is equal to the target temperature.
        //
        // Not specifying a value is equivalent to specifying a value of zero.
        //
        // The min_stable_duration must be less than or equal to the timeout duration
        // (if it were greater, then the temperature would never be read as 'stable' before
        // the time-out occurred).
        //
        // Since 3.4
        uint32 min_stable_duration = 3;

        // Specify an optional tolerance to apply to the wait.
        //
        // For example, if the target temperature is 35, and the tolerance is 1
        // any temperature in the range 34 - 36 will cause the request to return.
        //
        // Default is 0.5 degree tolerance.
        float tolerance = 2;
    }

    // The desired temperature in degrees Celsius.
    //
    // If temperature control is supported and enabled, the device will attempt to keep its
    // temperature at this value. See the ``can_set_temperature`` field returned by the
    // DeviceService.get_device_info() RPC.
    float temperature = 1;

    // Settings which can be specified in order to wait for the temperature to be reached.
    //
    // If this is not set at all, not waiting will be done. If it is set (even to an empty
    // WaitForTemperatureSettings object), the call will not return until either the temperature was
    // reached or the timeout was reached. In this case, on MinIONs and GridIONs, the ASIC power
    // will be enabled if it was not already. See acquisition.StopRequest.keep_power_on for more
    // details about the implications of this.
    //
    // Since 1.15
    WaitForTemperatureSettings wait_for_temperature = 2;
}

message SetTemperatureResponse {
    // Find if we hit a timeout waiting for the temperature to be hit.
    bool timed_out_waiting_for_temperature = 1;
}

message GetTemperatureRequest
{
}

message GetTemperatureResponse
{
    // Packet of temperatures appropriate for a MinION.
    message MinIONTemperature
    {
        // Temperature as measured by the probe inside the asic.
        google.protobuf.FloatValue asic_temperature = 1;
        // Temperature as measured by the probe in the minion heatsink.
        google.protobuf.FloatValue heatsink_temperature = 2;
    }

    // Packet of temperatures appropriate for a PromethION.
    message PromethIONTemperature
    {
        // Temperature as measured by thermistor TH2 on the P-Chip.
        google.protobuf.FloatValue flowcell_temperature = 1;

        // Mean of 12 pixel-blocks temperatures measured with sensors in the ASIC.
        google.protobuf.FloatValue chamber_temperature = 2;
    }

    oneof temperature {
        MinIONTemperature minion = 1;
        PromethIONTemperature promethion = 2;
    }

    // Return the temperature target the device is aiming to reach.
    //
    // Since 1.15
    google.protobuf.FloatValue target_temperature = 3;
}

message StreamTemperatureRequest {
    // How often temperature updates should be sent
    // Defaults to a period of 1 second, if not specified, or set to 0
    uint32 period_seconds = 1;
}

message UnblockRequest
{
    // List of channels indexed from 1.
    repeated uint32 channels = 1;

    // How long should an unblock last.
    oneof duration{
        uint32 duration_in_seconds = 2;
        uint32 duration_in_milliseconds = 3;
    }
}
message UnblockResponse{}

message CancelUnblocksRequest
{
}

message CancelUnblocksResponse
{
    // The number of unblocks which have been cancelled as part of this request.
    //
    // Should return the total number of unblock operations which have been cancelled.
    //
    uint32 cancelled_unblocks = 1;
}

enum SelectedWell {
    WELL_NONE   = 0;
    WELL_1      = 1;
    WELL_2      = 2;
    WELL_3      = 3;
    WELL_4      = 4;
    WELL_OTHER  = 5;
}

message GetChannelConfigurationRequest
{
    // A list of channel names (1-indexed) to specify what channels to get channel configs for
    //
    // Will return an error if any of the channel names are below 1, or above the channel count value
    // returned from :meth:`get_flow_cell_info`
    repeated uint32 channels = 1;
}

message GetChannelConfigurationResponse
{
    // A list of channel configurations
    //
    // The order of channel configurations matches the channel order specified by :attribute:`channels`
    // in the request message
    repeated ReturnedChannelConfiguration channel_configurations = 1;
}

message SetChannelConfigurationRequest
{
    // A map between <channel name, config to set>
    //
    // Will return an error if any of the key values (representing channel names) are below 1, or
    // above the channel count value returned from :meth:`get_flow_cell_info`
    //
    // The selected well cannot be set to WELL_OTHER, and will error if it tries to do so
    //
    // DEPRECATED: Note that the type to set may change from 4.0 to enforce the fact that
    // unblock cannot be set through this call
    map<uint32, ChannelConfiguration> channel_configurations = 1;
}

message SetChannelConfigurationResponse
{
}

message SetChannelConfigurationAllRequest
{
    ChannelConfiguration channel_configuration = 1 [(rpc_unwrap) = true];
}

message SetChannelConfigurationAllResponse
{
}

message SaturationConfig
{
    // The thresholds define how many over limit samples
    // are required to trigger saturation on the device.
    //
    // Each packet of frames minknow receive is delivered to the saturation
    // check (in approx 64 frame chunks), only the first frame of each packet is inspected.
    // The thresholds control how many _packets_ must be outside the valid range.
    // ie. if general_threshold is set to 10, at least 640 frames are
    // required to trigger saturation.
    //
    // It is also possible to not define the value to never
    // trigger saturation in this config.
    message Thresholds
    {
        // Note: Setting a saturation threshold to 0 will prevent the threshold from triggering.

        // Threshold for software saturation on all non-unblock muxes
        google.protobuf.UInt32Value general_threshold = 1;
        // Threshold for software saturation on unblock muxes
        google.protobuf.UInt32Value unblock_threshold = 2;
        // Threshold for user threshold  saturation on all non-unblock muxes
        google.protobuf.UInt32Value user_general_threshold = 3;
        // Threshold for user threshold saturation on unblock muxes
        google.protobuf.UInt32Value user_unblock_threshold = 4;
    }

    // The ranges specify the actual pA or ADC ranges which will trigger saturation.
    // This range is checked against the first sample in each delivered packet.
    //
    // software saturation is specified in adc units
    message SoftwareSaturation
    {
        // Set to enable or disable software saturation.
        bool enabled = 1;

        // The minimum adc value that is not a saturation.
        //
        // If this value is not specified, the previous value is kept.
        google.protobuf.Int32Value software_min_adc = 2;

        // The maximum adc value that is not a saturation.
        //
        // If this value is not specified, the previous value is kept.
        google.protobuf.Int32Value software_max_adc = 3;
    }

    // User threshold is specified in pico amps
    message UserThresholdSaturation
    {
        // Set to enable or disable software saturation.
        bool enabled = 1;

        // The minimum pA value that is not a saturation.
        //
        // If this value is not specified, the previous value is kept.
        google.protobuf.FloatValue user_threshold_min_pa = 2;

        // The maximum pA value that is not a saturation.
        //
        // If this value is not specified, the previous value is kept.
        google.protobuf.FloatValue user_threshold_max_pa = 3;
    }

    // Settings for saturation count thresholds, this controls how long a
    // saturated value must be over limit before the channel is turned off.
    //
    // If not specified, the previous thresholds are kept.
    Thresholds thresholds = 1;

    // Settings for software saturation, specified in adc units of the device.
    //
    // If not specified, the previous thresholds are kept.
    SoftwareSaturation software_saturation = 2;

    // Settings for user threshold saturation, specified in pA.
    //
    // If not specified, the previous thresholds are kept.
    UserThresholdSaturation user_threshold_saturation = 3;
}

message SetSaturationConfigRequest
{
    SaturationConfig settings = 1 [(rpc_unwrap) = true];
}

message SetSaturationConfigResponse
{
}

message GetSaturationConfigRequest
{
}

message GetSaturationConfigResponse
{
    SaturationConfig settings = 1 [(rpc_unwrap) = true];
}

message GetSampleRateRequest
{
}

message GetSampleRateResponse
{
    uint32 sample_rate = 1;
}

message SetSampleRateRequest
{
    uint32 sample_rate = 1 [(rpc_required) = true];
}

message SetSampleRateResponse
{
    // The real sample rate is the actual sample rate that is set on the device, which
    // may be different from the actual value passed into the rpc.
    //
    // For example on promethion, when it is given a sample rate, it will round to the nearest
    // 1000. So 1499 becomes 1000 and 1500 becomes 2000 real sample rate
    //
    // For a minion, the actual sample rate is determined via 3 separate values; clock speed,
    // integration time and clock divider, and so not all values are possible. e.g. setting 3000
    // will return 3012 real sample rate. See 'sampling_frequency' in MinionDeviceService for a
    // slightly more in depth explanation
    uint32 real_sample_rate = 1;
}
message GetBiasVoltageRequest {

}

message GetBiasVoltageResponse {
    double bias_voltage = 1;
}

message SetBiasVoltageRequest {
    double bias_voltage = 1 [(rpc_required) = true];
}

message SetBiasVoltageResponse {

}

message DumpStateRequest {
}

message DumpStateResponse {
}