Integração Opentrons

Visão Geral

Crie protocolos Python Protocol API v2 voltados para produção para Opentrons Flex e OT-2. Esta habilidade abrange estrutura de protocolo, configuração de hardware e deck, manuseio de líquidos, personalização em tempo de execução, controle de módulos, simulação e implantação segura.

A linha de base verificada em 2026-10-01 é:

• opentrons==10.0.0 para simulação Flex reproduzível.
• opentrons==9.0.0 para simulação de compatibilidade local com OT-2 API 2.28.
• Flex suporta níveis de API de 2.15 a 2.30 no software atual.
• OT-2 suporta níveis de API de 2.0 a 2.28 no software atual.
• API 2.29 e posteriores são apenas para Flex nesta linha de base. Mantenha o OT-2 em 2.28 ou inferior.
• Os modelos Flex incluídos mantêm a API 2.29 porque o agrupamento de etapas é o recurso mais recente necessário. A API 2.30 corrige a aspiração do menisco apenas no início.
• A biblioteca 10.0.0 relata um máximo local de 2.31, à frente do máximo documentado do robô de 2.30. Não infira suporte ao robô dessa constante.

Leia references/sources.md para a documentação upstream usada para este instantâneo. Verifique novamente a página oficial de versionamento antes de direcionar um software de robô mais recente.

Limite de Segurança

Os protocolos Opentrons controlam equipamentos físicos. Nunca trate a sintaxe Python bem-sucedida ou a simulação local como permissão para executar em um robô.

Antes da execução ao vivo:

1. Simule localmente com a mesma versão fixada de opentrons usada para autoria.
2. Importe o protocolo para o Opentrons App correto e exija análise bem-sucedida.
3. Verifique o modelo do robô, software, pipetas, suportes, módulos, adaptadores, definições de labware, fixações de deck, contagem de pontas, volumes de origem, volumes mortos e capacidade de destino.
4. Revise a pré-visualização da execução e o mapa do deck com o operador.
5. Realize uma execução a seco lenta com líquido não perigoso quando geometria, labware personalizado, coleta parcial de ponta ou movimentos de garra forem novos.
6. Mantenha o botão de parada de emergência acessível e siga os procedimentos específicos do local para biossegurança, segurança química e controle de contaminação.

A simulação não pode verificar calibração física, propriedades do líquido, comportamento do menisco, tolerâncias de fabricação de labware, remoção de tampas ou selos, tubulações ou todas as possíveis colisões.

Escolha a Interface Certa

Use esta habilidade para arquivos Python importados no Opentrons App e executados através da Protocol API.

• Use o Protocol Designer para fluxos de trabalho sem código suportados.
• Use o PyLabRobot para um fluxo de trabalho independente de hardware que abrange vários fornecedores.
• Trate a API HTTP do robô como uma superfície de integração separada. Se o controle HTTP direto for explicitamente necessário, use o documento OpenAPI servido pelo robô de destino e não infira endpoints dos métodos da Protocol API.

Entrada Necessária

Não escreva o código final do protocolo até que estes fatos sejam conhecidos:

• Robô: Flex ou OT-2, mais o software do robô instalado.
• Modelo da pipeta, faixa de volume, contagem de canais e suporte.
• Módulos e gerações; disponibilidade do Flex Gripper ou Stacker.
• Nomes de carregamento exatos da API de labware e arquivos de definição personalizados, se houver.
• Fixações de deck: lixeira Flex, calha de resíduos, slots de estágio ou Stackers.
• Volumes de origem, volumes de destino, volume morto, necessidades de mistura e características do líquido.
• Política de pontas: limites de contaminação, política de reutilização, filtros, coleta parcial e pontas totais.
• Intervenções do operador, tempo de incubação, parâmetros de tempo de execução e arquivos de saída.
• Critérios de aceitação: erro de volume tolerado, controles necessários e plano de execução a seco.

Se alguma configuração física for incerta, produza um rascunho parametrizado e uma lista explícita de suposições em vez de adivinhar.

Instalar e Simular

Flex:

uv run --no-project --isolated --python 3.12 --with "opentrons==10.0.0" opentrons_simulate protocol.py

OT-2 API 2.28:

uv run --no-project --isolated --python 3.12 --with "opentrons==9.0.0" opentrons_simulate protocol.py

O pacote 10.0.0 rejeita protocolos OT-2 após a divisão da linha de lançamento Flex/OT-2. Sempre conclua a análise do OT-2 no Opentrons App atual.

Para um ambiente Flex dedicado:

uv venv --python 3.12 .venv-opentrons
uv pip install --python .venv-opentrons/bin/python -r skills/opentrons-integration/requirements-flex.txt
.venv-opentrons/bin/opentrons_simulate protocol.py

Use requirements-ot2.txt em vez disso para um ambiente de compatibilidade OT-2. No Windows, invoque o executável de .venv-opentrons\Scripts\opentrons_simulate.exe. A simulação local é para protocolos Python; importe arquivos JSON do Protocol Designer no Opentrons App apropriado em vez disso.

…