Conector de adaptadores de protocolo Modbus-RTU - AWS IoT Greengrass
RequisitosParâmetrosDados de entradaDados de saídaRespostas e solicitações Modbus RTUExemplo de usoLicençasChangelogConsulte também

AWS IoT Greengrass Version 1 entrou na fase de vida útil prolongada em 30 de junho de 2023. Para obter mais informações, consulte política de manutenção do AWS IoT Greengrass V1. Após essa data, AWS IoT Greengrass V1 não lançaremos atualizações que forneçam recursos, aprimoramentos, correções de erros ou patches de segurança. Os dispositivos que funcionam AWS IoT Greengrass V1 não serão interrompidos e continuarão operando e se conectando à nuvem. É altamente recomendável que você migre para AWS IoT Greengrass Version 2, o que adiciona novos recursos significativos e suporte para plataformas adicionais.

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Conector de adaptadores de protocolo Modbus-RTU

O conector de adaptadores de protocolo Modbus-RTU pesquisa informações dos dispositivos Modbus RTU que estão no grupo AWS IoT Greengrass.

Esse conector recebe parâmetros para uma solicitação Modbus RTU de uma função do Lambda definida pelo usuário. Ele envia a solicitação correspondente e, em seguida, publica a resposta do dispositivo de destino como uma mensagem MQTT.

Esse conector tem as seguintes versões.

Versão

ARN

3

arn:aws:greengrass:region::/connectors/ModbusRTUProtocolAdapter/versions/3

2

arn:aws:greengrass:region::/connectors/ModbusRTUProtocolAdapter/versions/2

1

arn:aws:greengrass:region::/connectors/ModbusRTUProtocolAdapter/versions/1

Para obter informações sobre alterações de versão, consulte o Changelog.

Requisitos

Esse conector tem os seguintes requisitos:

Version 3

  • Software de núcleo do AWS IoT Greengrass v1.9.3 ou versão posterior.

  • Python, versão 3.7 ou 3.8, instalado no dispositivo de núcleo e adicionado à variável de ambiente PATH.

    nota

    Para usar o Python 3.8, execute o comando a seguir para criar um symblink da pasta de instalação padrão do Python 3.7 para os binários instalados do Python 3.8.

    sudo ln -s path-to-python-3.8/python3.8 /usr/bin/python3.7

    Isso configura seu dispositivo para atender ao requisito Python para AWS IoT Greengrass.

  • Uma conexão física entre o núcleo AWS IoT Greengrass e os dispositivos Modbus. O núcleo deve estar fisicamente conectado à rede Modbus RTU por meio de uma porta serial, por exemplo, uma porta USB.

  • Um recurso do dispositivo local no grupo do Greengrass que aponta para a porta serial Modbus física.

  • Uma função do Lambda definida pelo usuário que envia parâmetros de solicitação Modbus RTU para esse conector. Os parâmetros de solicitação devem estar em conformidade com os padrões esperados e incluir os IDs e os endereços dos dispositivos de destino na rede Modbus RTU. Para obter mais informações, consulte Dados de entrada.

Versions 1 - 2

  • Software AWS IoT Greengrass Core v1.7 ou posterior.

  • Python versão 2.7 instalado no dispositivo de núcleo e adicionado à variável de ambiente PATH.

  • Uma conexão física entre o núcleo AWS IoT Greengrass e os dispositivos Modbus. O núcleo deve estar fisicamente conectado à rede Modbus RTU por meio de uma porta serial, por exemplo, uma porta USB.

  • Um recurso do dispositivo local no grupo do Greengrass que aponta para a porta serial Modbus física.

  • Uma função do Lambda definida pelo usuário que envia parâmetros de solicitação Modbus RTU para esse conector. Os parâmetros de solicitação devem estar em conformidade com os padrões esperados e incluir os IDs e os endereços dos dispositivos de destino na rede Modbus RTU. Para obter mais informações, consulte Dados de entrada.

Parâmetros do conector

Esse conector oferece suporte aos seguintes parâmetros:

ModbusSerialPort-ResourceId

O ID do recurso de dispositivo local que representa a porta serial Modbus física.

nota

Esse conector recebe acesso de leitura e gravação ao recurso.

Nome de exibição no console AWS IoT: Recurso de porta serial Modbus

Obrigatório: true

Digite: string

Padrão válido: .+

ModbusSerialPort

O caminho absoluto para a porta serial Modbus física no dispositivo. Este é o caminho de origem especificado para o recurso de dispositivo local Modbus.

Nome de exibição no console AWS IoT: Caminho de origem do recurso da porta serial Modbus

Obrigatório: true

Digite: string

Padrão válido: .+

Exemplo de criação de conector (AWS CLI)

O seguinte comando da CLI cria um ConnectorDefinition com uma versão inicial que contém o conector adaptador de protocolo Modbus-RTU.

aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{
    "Connectors": [
        {
            "Id": "MyModbusRTUProtocolAdapterConnector",
            "ConnectorArn": "arn:aws:greengrass:region::/connectors/ModbusRTUProtocolAdapter/versions/3",
            "Parameters": {
                "ModbusSerialPort-ResourceId": "MyLocalModbusSerialPort",
                "ModbusSerialPort": "/path-to-port"
            }
        }
    ]
}'
nota

A função do Lambda nesse conector tem um ciclo de vida longo.

No console do AWS IoT Greengrass, você pode adicionar um conector na página Conectores do grupo. Para obter mais informações, consulte Conceitos básicos de conectores do Greengrass (console).

nota

Depois de implantar o conector adaptador de protocolo Modbus-RTU, você pode usar o AWS IoT Things Graph para orquestrar as interações entre dispositivos no seu grupo. Para obter mais informações, consulte Modbus no Guia do usuário do AWS IoT Things Graph.

Dados de entrada

Esse conector aceita parâmetros de solicitação Modbus RTU de uma função do Lambda definida pelo usuário em um tópico MQTT. As mensagens de entrada devem estar no formato JSON.

Filtro de tópico na assinatura

modbus/adapter/request

Propriedades de mensagens

A mensagem de solicitação varia de acordo com o tipo de solicitação Modbus RTU que ela representa. As propriedades a seguir são necessárias para todas as solicitações:

  • No objeto request:

    • operation. O nome da operação a ser executada. Por exemplo, especifique "operation": "ReadCoilsRequest" para boninas de leitura. Esse valor deve ser uma string Unicode. Para ver as operações suportadas, consulte Respostas e solicitações Modbus RTU.

    • device. O dispositivo de destino da solicitação. O valor deve estar entre 0 - 247.

  • A propriedade id. Um ID para a solicitação. Esse valor é usado para a eliminação de duplicação de dados e é retornado da forma que se encontra na propriedade id de todas as respostas, incluindo respostas de erro. Esse valor deve ser uma string Unicode.

nota

Se sua solicitação incluir um campo de endereço, você deve especificar o valor como um inteiro. Por exemplo, "address": 1.

Os outros parâmetros a ser incluídos na solicitação dependem da operação. Todos os parâmetros de solicitação são necessários, exceto o CRC, que é tratado separadamente. Para ver exemplos, consulte Exemplos de solicitações e respostas.

Exemplo de entrada: solicitação de bobinas de leitura
{
    "request": {
        "operation": "ReadCoilsRequest",
    	"device": 1,
    	"address": 1,
    	"count": 1
    },
    "id": "TestRequest"
}

Dados de saída

Esse conector publica respostas em solicitações Modbus RTU de entrada.

Filtro de tópico na assinatura

modbus/adapter/response

Propriedades de mensagens

O formato da mensagem de resposta varia de acordo com a solicitação correspondente e o status da resposta. Para ver exemplos, consulte Exemplos de solicitações e respostas.

nota

Uma resposta para uma operação de gravação é simplesmente um eco da solicitação. Embora nenhuma informação significativa seja retornada para respostas de gravação, é uma boa prática verificar o status da resposta.

Cada resposta inclui as seguintes propriedades:

  • No objeto response:

    • status. O status da solicitação. O status pode ser um dos valores a seguir:

      • Success. A solicitação era válida, enviada para a rede Modbus RTU, e uma resposta foi retornada.

      • Exception. A solicitação era válida, enviada para a rede Modbus RTU, e uma resposta de exceção foi retornada. Para obter mais informações, consulte Status da resposta: Exceção.

      • No Response. A solicitação era inválida, e o conector capturou o erro antes que a solicitação fosse enviada por meio da rede Modbus RTU. Para obter mais informações, consulte Status de resposta: Sem resposta.

    • device. O dispositivo para o qual a solicitação foi enviada.

    • operation. O tipo de solicitação que foi enviada.

    • payload. O conteúdo da resposta que foi retornada. Se status for No Response, esse objeto conterá apenas uma propriedade error com a descrição do erro (por exemplo, "error": "[Input/Output] No Response received from the remote unit").

  • A propriedade id. O ID da solicitação, usado para eliminação de duplicação de dados.

Exemplo de resultado: sucesso
{
    "response" : {
        "status" : "success",
        "device": 1,
    	"operation": "ReadCoilsRequest",
    	"payload": {
        	"function_code": 1,
        	"bits": [1]
    	}
     },
     "id" : "TestRequest"
}
Exemplo de resultado: falha
{
    "response" : {
        "status" : "fail",
        "error_message": "Internal Error",
        "error": "Exception",
        "device": 1,
    	"operation": "ReadCoilsRequest",
    	"payload": {
        	"function_code": 129,
        	"exception_code": 2
    	}
     },
     "id" : "TestRequest"
}

Para obter mais exemplos, consulte Exemplos de solicitações e respostas.

Respostas e solicitações Modbus RTU

Esse conector aceita parâmetros de solicitação Modbus RTU como dados de entrada e publica respostas como dados de saída.

As operações comuns a seguir têm suporte.

Nome da operação na solicitação Código da função em resposta
ReadCoilsRequest 01
ReadDiscreteInputsRequest 02
ReadHoldingRegistersRequest 03
ReadInputRegistersRequest 04
WriteSingleCoilRequest 05
WriteSingleRegisterRequest 06
WriteMultipleCoilsRequest 15
WriteMultipleRegistersRequest 16
MaskWriteRegisterRequest 22
ReadWriteMultipleRegistersRequest 23

Veja a seguir exemplos de solicitações e respostas para operações com suporte.

Bobinas de leitura

Exemplo de solicitação:

{
    "request": {
        "operation": "ReadCoilsRequest",
    	"device": 1,
    	"address": 1,
    	"count": 1
    },
    "id": "TestRequest"
}

Exemplo de resposta:

{
    "response": {
        "status": "success",
        "device": 1,
    	"operation": "ReadCoilsRequest",
    	"payload": {
        	"function_code": 1,
        	"bits": [1]
    	}
     },
     "id" : "TestRequest"
}
Ler entradas discretas

Exemplo de solicitação:

{
    "request": {
        "operation": "ReadDiscreteInputsRequest",
        "device": 1,
        "address": 1,
        "count": 1
    },
    "id": "TestRequest"
}

Exemplo de resposta:

{
    "response": {
        "status": "success",
        "device": 1,
        "operation": "ReadDiscreteInputsRequest",
        "payload": {
            "function_code": 2,
            "bits": [1]
        }
     },
     "id" : "TestRequest"
}
Registros de leitura em espera

Exemplo de solicitação:

{
    "request": {
        "operation": "ReadHoldingRegistersRequest",
    	"device": 1,
    	"address": 1,
    	"count": 1
    },
    "id": "TestRequest"
}

Exemplo de resposta:

{
    "response": {
        "status": "success",
        "device": 1,
    	"operation": "ReadHoldingRegistersRequest",
    	"payload": {
    	    "function_code": 3,
            "registers": [20,30]
    	}
     },
     "id" : "TestRequest"
}
Registros de entrada de leitura

Exemplo de solicitação:

{
    "request": {
        "operation": "ReadInputRegistersRequest",
    	"device": 1,
    	"address": 1,
    	"value": 1
    },
    "id": "TestRequest"
}
Bobina de gravação única

Exemplo de solicitação:

{
    "request": {
        "operation": "WriteSingleCoilRequest",
    	"device": 1,
    	"address": 1,
    	"value": 1
    },
    "id": "TestRequest"
}

Exemplo de resposta:

{
    "response": {
        "status": "success",
        "device": 1,
    	"operation": "WriteSingleCoilRequest",
    	"payload": {
    	    "function_code": 5,
    	    "address": 1,
    	    "value": true
    	}
     },
     "id" : "TestRequest"
Registro de gravação único

Exemplo de solicitação:

{
    "request": {
        "operation": "WriteSingleRegisterRequest",
    	"device": 1,
    	"address": 1,
    	"value": 1
    },
    "id": "TestRequest"
}
Várias bobinas de gravação

Exemplo de solicitação:

{
    "request": {
        "operation": "WriteMultipleCoilsRequest",
    	"device": 1,
    	"address": 1,
    	"values": [1,0,0,1]
    },
    "id": "TestRequest"
}

Exemplo de resposta:

{
    "response": {
        "status": "success",
        "device": 1,
    	"operation": "WriteMultipleCoilsRequest",
    	"payload": {
    	    "function_code": 15,
    	    "address": 1,
    	    "count": 4
    	}
     },
     "id" : "TestRequest"
}
Vários registros de gravação

Exemplo de solicitação:

{
    "request": {
        "operation": "WriteMultipleRegistersRequest",
    	"device": 1,
    	"address": 1,
    	"values": [20,30,10]
    },
    "id": "TestRequest"
}

Exemplo de resposta:

{
    "response": {
        "status": "success",
        "device": 1,
    	"operation": "WriteMultipleRegistersRequest",
    	"payload": {
    	    "function_code": 23,
    	    "address": 1,
       		"count": 3
    	}
     },
     "id" : "TestRequest"
}
Registro de gravação Mask

Exemplo de solicitação:

{
    "request": {
        "operation": "MaskWriteRegisterRequest",
    	"device": 1,
    	"address": 1,
        "and_mask": 175,
        "or_mask": 1
    },
    "id": "TestRequest"
}

Exemplo de resposta:

{
    "response": {
        "status": "success",
        "device": 1,
    	"operation": "MaskWriteRegisterRequest",
    	"payload": {
    	    "function_code": 22,
            "and_mask": 0,
            "or_mask": 8
    	}
     },
     "id" : "TestRequest"
}
Vários registros de leitura/gravação

Exemplo de solicitação:

{
    "request": {
        "operation": "ReadWriteMultipleRegistersRequest",
    	"device": 1,
    	"read_address": 1,
        "read_count": 2,
        "write_address": 3,
        "write_registers": [20,30,40]
    },
    "id": "TestRequest"
}

Exemplo de resposta:

{
    "response": {
        "status": "success",
        "device": 1,
    	"operation": "ReadWriteMultipleRegistersRequest",
    	"payload": {
    	    "function_code": 23,
    	    "registers": [10,20,10,20]
    	}
     },
     "id" : "TestRequest"
}
nota

Os registros retornados nessa resposta são os registos lidos.

As exceções pode ocorrer quando o formato da solicitação é válido, mas a solicitação não é concluída com êxito. Nesse caso, a resposta contém as seguintes informações:

  • O status é definido como Exception.

  • O código da função function_code é igual ao código da função da solicitação + 128.

  • O exception_code contém o código da exceção. Para obter mais informações, consulte os códigos de exceção Modbus.

Exemplo:

{
    "response" : {
        "status" : "fail",
        "error_message": "Internal Error",
        "error": "Exception",
        "device": 1,
    	"operation": "ReadCoilsRequest",
    	"payload": {
        	"function_code": 129,
        	"exception_code": 2
    	}
     },
     "id" : "TestRequest"
}

Esse conector executa verificações de validação na solicitação Modbus. Por exemplo, ele verifica se há formatos inválidos e campos ausentes. Se a validação falhar, o conector não enviará a solicitação. Em vez disso, ele retornará uma resposta com as seguintes informações:

  • O status é definido como No Response.

  • O error contém o motivo do erro.

  • O error_message contém a mensagem do erro.

Exemplos:

{
    "response" : {
        "status" : "fail",
        "error_message": "Invalid address field. Expected <type 'int'>, got <type 'str'>",
        "error": "No Response",
        "device": 1,
    	"operation": "ReadCoilsRequest",
    	"payload": {
        	"error": "Invalid address field. Expected <type 'int'>, got <type 'str'>"
    	}
     },
     "id" : "TestRequest"
}

Se a solicitação tem como destino um dispositivo inexistente, ou se a rede Modbus RTU não está funcionando, você pode obter um ModbusIOException, que usa o formato Sem resposta.

{
    "response" : {
        "status" : "fail",
        "error_message": "[Input/Output] No Response received from the remote unit",
        "error": "No Response",
        "device": 1,
    	"operation": "ReadCoilsRequest",
    	"payload": {
        	"error": "[Input/Output] No Response received from the remote unit"
    	}
     },
     "id" : "TestRequest"
}

Exemplo de uso

Use as seguintes etapas de alto nível para configurar um exemplo de função do Lambda Python 3.7 que pode ser usado para testar o conector.

nota

  1. Certifique-se de cumprir os requisitos para o conector.

  2. Crie e publique uma função do Lambda que envie dados de entrada para o conector.

    Salve o código de exemplo como arquivo PY. Baixe e descompacte o SDK do Core AWS IoT Greengrass para Python. Crie então um pacote zip que contenha o arquivo PY e a pasta greengrasssdk no nível raiz. Este pacote zip é o pacote de implantação que você transfere por upload para o AWS Lambda.

    Depois de criar a função do Lambda Python 3.7, publique uma versão de função e crie um alias.

  3. Configure o grupo do Greengrass.

    1. Adicione a função do Lambda pelo seu alias (recomendado). Configure o ciclo de vida do Lambda como de longa duração (ou "Pinned": true na CLI).

    2. Adicione o recurso de dispositivo local necessário e conceda acesso de leitura/gravação à função do Lambda.

    3. Adicione o conector e configure seus parâmetros.

    4. Adicione assinaturas que permitam que o conector receba dados de entrada e envie dados de saída em filtros de tópico compatíveis.

      • Defina a função do Lambda como origem, o conector como destino e use um filtro de tópico de entrada compatível.

      • Defina o conector como origem, o AWS IoT Core como destino, e use um filtro de tópico de saída compatível. Use essa assinatura para exibir mensagens de status no console do AWS IoT.

  4. Implante o grupo.

  5. No console do AWS IoT, na página Teste, assine o tópico de dados de saída para exibir mensagens de status do conector. A função de exemplo do Lambda é de longa duração e começa a enviar mensagens imediatamente após o grupo ser implantado.

    Ao finalizar o teste, você pode definir o ciclo de vida do Lambda como sob demanda (ou "Pinned": false na CLI) e implantar o grupo. Isso impede o envio de mensagens pela função.

Exemplo

O exemplo a seguir da função do Lambda envia uma mensagem de entrada para o conector.

import greengrasssdk
import json

TOPIC_REQUEST = 'modbus/adapter/request'

# Creating a greengrass core sdk client
iot_client = greengrasssdk.client('iot-data')

def create_read_coils_request():
	request = {
		"request": {
			"operation": "ReadCoilsRequest",
			"device": 1,
			"address": 1,
			"count": 1
		},
		"id": "TestRequest"
	}
	return request

def publish_basic_request():
	iot_client.publish(payload=json.dumps(create_read_coils_request()), topic=TOPIC_REQUEST)

publish_basic_request()

def lambda_handler(event, context):
	return

Licenças

O conector adaptador de protocolo Modbus-RTU inclui o seguinte licenciamento/software de terceiros:

Esse conector é liberado de acordo com o Contrato de licença de software do Greengrass Core.

Changelog

A tabela a seguir descreve as alterações em cada versão do conector.

Versão

Alterações

3

Atualização do runtime do Lambda para Python 3.7, o que altera o requisito de runtime.

2

ARN do conector atualizado para suporte Região da AWS.

Melhoria do registro em log de erros.

1

Versão inicial.

Um grupo do Greengrass só pode conter uma versão do conector por vez. Para obter informações sobre como fazer upgrade de uma versão do conector, consulte Atualizar a versões do conector.

Consulte também