Version 5.5.2 bump

dev-requirements.txt

@@ -1,4 +1,5 @@
-grpcio-tools
+grpcio==1.41.0
+grpcio-tools==1.41.0
 minknow-api-service-plugin
 pre-commit
 pytest

proto/minknow_api/analysis_configuration.proto

@@ -1007,9 +1007,14 @@ message WriterConfiguration {
         // when the fastq is generated.
         string fastq_header_pattern = 9;
 
-        // How many reads are placed in each file (after batch_count files {batch_number}
-        // is increased in the filename).
-        uint32 batch_count = 10;
+        oneof batch_info {
+            // How many reads are placed in each batch (after batch_count reads {batch_number}
+            // is increased in the pattern).
+            uint32 batch_count = 10;
+
+            // Number of estimated bases within a batch before it rotates to a new batch
+            uint64 bases_per_batch = 15;
+        }
     }
 
     message ReadFastqConfiguration {
@@ -1031,8 +1036,14 @@ message WriterConfiguration {
         // when the fastq is generated.
         string header_pattern = 3;
 
-        // How many files are placed in each batch (after batch_count files {batch_number} is increased in the filename).
-        uint32 batch_count = 4;
+        oneof batch_info {
+            // How many reads are placed in each batch (after batch_count reads {batch_number}
+            // is increased in the pattern).
+            uint32 batch_count = 4;
+
+            // Number of estimated bases within a batch before it rotates to a new batch
+            uint64 bases_per_batch = 6;
+        }
 
         // Compress fastq files with gzip compression.
         // default: false
@@ -1051,8 +1062,14 @@ message WriterConfiguration {
         // See file pattern attributes above.
         string file_pattern = 2;
 
-        // How many files are placed in each batch (after batch_count files {batch_number} is increased in the filename).
-        uint32 batch_count = 3;
+        oneof batch_info {
+            // How many reads are placed in each batch (after batch_count reads {batch_number}
+            // is increased in the pattern).
+            uint32 batch_count = 3;
+
+            // Number of estimated bases within a batch before it rotates to a new batch
+            uint64 bases_per_batch = 5;
+        }
 
         // If true minknow will only write the primary alignment for each read.
         bool disable_writing_multiple_alignments = 4;
@@ -1070,10 +1087,14 @@ message WriterConfiguration {
         // See file pattern attributes above.
         string file_pattern = 2;
 
-        // How many files are placed in each batch (after batch_count files {batch_number} is increased in the filename).
-        //
-        // Set to zero to disable batching.
-        uint32 batch_count = 3;
+        oneof batch_info {
+            // How many reads are placed in each batch (after batch_count reads {batch_number}
+            // is increased in the pattern).
+            uint32 batch_count = 3;
+
+            // Number of estimated bases within a batch before it rotates to a new batch
+            uint64 bases_per_batch = 7;
+        }
 
         // Prevent reads which have successfully basecalled being written to pod5.
         bool disable_writing_passed_reads = 4;
@@ -1096,8 +1117,14 @@ message WriterConfiguration {
         // See file pattern attributes above.
         string file_pattern = 2;
 
-        // How many files are placed in each batch (after batch_count files {batch_number} is increased in the filename).
-        uint32 batch_count = 3;
+        oneof batch_info {
+            // How many reads are placed in each batch (after batch_count reads {batch_number}
+            // is increased in the pattern).
+            uint32 batch_count = 3;
+
+            // Number of estimated bases within a batch before it rotates to a new batch
+            uint64 bases_per_batch = 4;
+        }
     }
 
     message SequencingSummaryConfiguration {

proto/minknow_api/device.proto

@@ -139,8 +139,13 @@ service DeviceService {
         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.
+    // Set the target primary device temperature
+    //
+    // If the device is not temperature-controllable (see the fields
+    // `device.GetDeviceInfoResponse.can_set_temperature` and
+    // `minion_device.MinionDeviceSettings.enable_temperature_control`) then this call will have
+    // no effect
+    //
     rpc set_temperature (SetTemperatureRequest) returns (SetTemperatureResponse) {
         option idempotency_level = IDEMPOTENT;
     }
@@ -734,25 +739,112 @@ message SetTemperatureRequest {
     // 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.
+    // primary temperature at this value. The reading used as the "primary" temperature depends
+    // on the device:
+    // - For MinIONs, the primary temperature is the heatsink temperature
+    // - For PromethIONs, the primary temperature is the flow cell temperature
+    //
+    // (If temperature control is not supported or is not enabled, the call to `set_temperature`
+    // will fail with `FAILED_PRECONDITION`)
+    //
     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.
+    // If this is not set at all, no waiting will be done. If it is set (even to an empty
+    // WaitForTemperatureSettings object), the call will not return until either:
+    // - The target temperature was reached, or
+    // - The timeout was reached, or
+    // - The secondary temperature limits were exceeded
+    //
+    // If `wait_for_temperature` is supplied then, 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 SecondaryTemperatureLimits {
+        // The minimum permissible "secondary" temperature
+        float min = 1;
+        // The maximum permissible "secondary" temperature
+        float max = 2;
+    }
+
+    // Specify "secondary" temperature limits
+    //
+    // This field allows limits to be placed on the "secondary" temperature, while waiting for
+    // the primary temperature to reach its target value (as specified in the `temperature` field,
+    // above).
+    //
+    // The meaning of the "secondary" temperature depends on the device in question:
+    // - For MinIONs, this is the ASIC temperature (i.e. flow cell or flow cell adapter
+    //   temperature)
+    // - For PromethIONs, this is the "chamber" temperature (which is derived from the measurements
+    //   of the ASIC temperature)
+    //
+    // These limits are intended to act as a safeguard against the case where the flow cell does
+    // not have good thermal contact with temperature control hardware (e.g. if the flow cell was
+    // not fully seated when it was inserted into the device). In such cases, the flow cell
+    // temperature may rise high enough to damage the flow cell; these limits may be used to
+    // mitigate the risk of the flow cell temperature rising high enough to cause damage to the
+    // flow cell.
+    //
+    // If the secondary temperature exceeds the specified limits while waiting for the target
+    // temperature to be reached, then all temperature control settings are reset to the values
+    // they had prior to the call to `set_temperature()` being made.
+    //
+    // NB - These limits apply ONLY when waiting for the target temperature to be reached; once the
+    // call to `set_temperature()` returns, these limits are no longer checked.
+    //
+    // Since 5.5
+    SecondaryTemperatureLimits secondary_temperature_limits = 3;
 }
 
 message SetTemperatureResponse {
     // Find if we hit a timeout waiting for the temperature to be hit.
+    //
+    // Deprecated since 5.5; in favour of the `TIMED_OUT_WAITING_FOR_TEMPERATURE` result code.
     bool timed_out_waiting_for_temperature = 1;
+
+    enum SetTemperatureResult {
+        // The specified target temperature was set
+        // This result will be returned if the request did not specify `wait_for_temperature`
+        TARGET_TEMPERATURE_SET = 0;
+
+        // The target temperature was set successfully, and the requested temperature was reached
+        // while waiting for temperature
+        REACHED_TEMPERATURE = 1;
+
+        // The `wait_for_temperature` timeout expired while waiting for the target temperature to
+        // be reached.
+        //
+        // If this result is returned, then `timed_out_waiting_for_temperature` will be set to
+        // true
+        TIMED_OUT_WAITING_FOR_TEMPERATURE = 2;
+
+        // The secondary temperature limits were exceeded while waiting for the target temperature
+        // to be reached
+        // The temperature control state has been reset to the state it was in before the call to
+        //  `set_temperature()`
+        SECONDARY_TEMPERATURE_LIMITS_EXCEEDED = 3;
+    }
+
+    // The result of setting the temperature
+    //
+    // Since 5.5
+    //
+    // NB - before 5.5, checking this field will always return a value of `TARGET_TEMPERATURE_SET`
+    // The "real" value may be inferred as follows:
+    //  - If `wait_for_temperature` was NOT specified, the "real" result is
+    //    `TARGET_TEMPERATURE_SET`
+    //  - If `wait_for_temperature` was specified, and `timed_out_waiting_for_temperature` is
+    //    false, the "real" result is `REACHED_TEMPERATURE`
+    //  - If `wait_for_temperature` was specified, and `timed_out_waiting_for_temperature` is
+    //    true, the "real" result is `TIMED_OUT_WAITING_FOR_TEMPERATURE`
+    //  - Versions prior to 5.5 do not support setting the secondary temperature limit, and so (for
+    //    these versions) the "real" value can never be `SECONDARY_TEMPERATURE_LIMITS_EXCEEDED`
+    SetTemperatureResult result = 2;
 }
 
 message GetTemperatureRequest
@@ -765,18 +857,23 @@ message GetTemperatureResponse
     message MinIONTemperature
     {
         // Temperature as measured by the probe inside the asic.
+        // This is the "secondary" temperature
         google.protobuf.FloatValue asic_temperature = 1;
+
         // Temperature as measured by the probe in the minion heatsink.
+        // This is the "primary" temperature
         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.
+        // This is the "primary" temperature
         google.protobuf.FloatValue flowcell_temperature = 1;
 
         // Mean of 12 pixel-blocks temperatures measured with sensors in the ASIC.
+        // This is the "secondary" temperature
         google.protobuf.FloatValue chamber_temperature = 2;
     }
 

proto/minknow_api/manager.proto

@@ -1005,11 +1005,23 @@ message AddSimulatedDeviceRequest {
 
     // The name of the position, this must be unique and the correct format:
     //
-    // For MinIONs and MinION-mk1Cs, "MS" followed by five digits, eg: "MS12345".
-    // For GridIONs, "GS" followed by five digits, eg: "GS12345".
-    // For P2Solos, "P2S" followed by four digits, eg: "P2S1234".
+    // For MinION Mk1B and Mk1C: "MS" followed by five digits, eg: "MS12345".
+    // For GridION: "GS" followed by five digits, eg: "GS12345".
+    // For P2 Solo: "P2S_" followed by five digits, and then "-A" or "-B" eg: "P2S_12345-A".
     //
-    // PromethIONs position-names have no format restriction, but must be unique
+    // PromethION and P2 Solo position-names have no format restriction, but must be unique. It is
+    // strongly recommended to follow standard naming conventions:
+    //
+    // For PromethION: start with "1A" and then increase the number and/or the letter as you add
+    // more positions.
+    // For P2 Solo: use "P2S_00000-A" and "P2S_00000-B" (these fit the format of real P2 Solo devices,
+    // but do not correspond to any real device).
+    //
+    // Future versions might constrain PromethION and P2 Solo device names. Using the above
+    // suggestions should ensure that your code will continue to work.
+    //
+    // Note that MinKNOW Core 5.5 and earlier required the P2 Solo device name to be "P2S" followed
+    // by four digits. This is no longer recommended.
     string name = 1 [(rpc_required) = true];
 
     // The type of the simulated device to create.
@@ -1336,4 +1348,4 @@ message SetFeaturesRequest {
 
 message SetFeaturesResponse {
 
-}
+}

proto/minknow_api/promethion_device.proto

@@ -90,6 +90,8 @@ message DeviceSettings {
     google.protobuf.BoolValue saturation_control_enabled = 5;
 
     // Enable use of the fast calibration mode across the device
+    //
+    // DEPRECATED since 5.5. This will be removed in a future release.
     google.protobuf.BoolValue fast_calibration_enabled = 6;
 
     // If the device is capable (see device.get_device_info().temperature_controllable)

proto/minknow_api/protocol.proto

@@ -509,6 +509,12 @@ enum ProtocolState {
     // The protocol was terminated because MinKNOW could not send telemetry to start acquisition.
     PROTOCOL_FINISHED_UNABLE_TO_SEND_TELEMETRY = 7;
 
+    // The protocol was terminated because the flow cell was disconnected
+    PROTOCOL_FINISHED_WITH_FLOW_CELL_DISCONNECT = 8;
+
+    // The protocol was terminated because the device was disconnected
+    PROTOCOL_FINISHED_WITH_DEVICE_DISCONNECT = 9;
+
     // Enums 20-120 are "reserved" for any new script exit codes we may want to forward
 
     // The protocol has reported and error during calibration
@@ -549,13 +555,42 @@ enum ProtocolPhase {
     // It should move into PHASE_PAUSED within a short time.
     PHASE_PAUSING = 6;
 
+    // The protocol is paused due to high temperature
+    //
+    // The user will have to confirm if they want to proceed with sequencing before resuming
+    PHASE_BAD_TEMPERATURE_AUTOMATIC_PAUSE = 8;
+
     // The protocol is in the process of resuming from a paused state.
     //
     // It should move into another phase, such as PHASE_SEQUENCING or PHASE_PREPARING_FOR_MUX_SCAN,
     // in a short time.
     PHASE_RESUMING = 7;
 }
 
+message RequestOrigin {
+    // 'User' based changes will typically come from calls made by the UI
+    // such as 'stop_protocol'
+    message User {}
+    // A request from minknow will usually come in the form of something ending
+    // naturally, or an error occuring where minknow has to take action
+    message MinKNOW {}
+    // The protocol script/bream is mainly responsible for making changes via
+    // protocol_phase_management
+    message ProtocolPhaseManagement {}
+    // A request made by the run until script due to certain criteria being met
+    message RunUntil {
+        // What criteria caused the state change
+        string criteria = 1;
+    }
+
+    oneof origin {
+        User user = 1;
+        MinKNOW minknow = 2;
+        ProtocolPhaseManagement protocol_phase_management = 3;
+        RunUntil run_until = 4;
+    }
+}
+
 message Epi2meWorkflowReference {
     // The unique identifier for a workflow ( unique to a specific instance of epi2me )
     int64 id = 1;
@@ -662,6 +697,14 @@ message ProtocolRunInfo {
     // Unset if the protocol is still running.
     google.protobuf.Timestamp end_time = 6;
 
+    // Who is responsible for stopping the protocol
+    //
+    // Candidates:
+    //  MinKNOW:     Any error that causes the protocol to stop
+    //  UI:          Through stop_protocol API
+    //  RunUntil:    Through stop criteria
+    RequestOrigin stop_origin = 23;
+
     // A list of acquisition periods started whilst this protocol was running.
     //
     repeated string acquisition_run_ids = 7;

proto/minknow_api/report_data.proto

@@ -6,8 +6,12 @@ import "minknow_api/acquisition.proto";
 import "minknow_api/instance.proto";
 import "minknow_api/log.proto";
 import "minknow_api/protocol.proto";
+import "minknow_api/run_until.proto";
 import "minknow_api/statistics.proto";
 
+import "google/protobuf/timestamp.proto";
+
+
 enum AcquisitionOutputTypes {
     AllData = 0;
     SplitByBarcodeAndAlignment = 1;
@@ -54,6 +58,8 @@ message AcquistionReportData {
     repeated ReadLengthHistogram read_length_histogram = 8;
 
     repeated BasecallBoxplot basecall_boxplot = 9;
+
+    run_until.Update run_until_update = 10;
 }
 
 // This is a subset of the information available from the describe_host() call
@@ -75,4 +81,7 @@ message ReportData {
 
     // All the user messages from protocol start to protocol end.
     repeated log.UserMessage user_messages = 5;
+
+    // The time at which the report data was generated (UTC)
+    google.protobuf.Timestamp report_data_generation_time = 6;
 }