MIMIC® Online Documentation

<< Previous Section    Next Section >>

MIMIC CoAP Protocol Module Guide

  1. Table of Contents

  2. Overview

    The MIMIC CoAP Protocol Module is an optional facility that simulates the Internet of Things (IoT) Constrained Application Protocol (CoAP) standard as detailed on IETF RFC 7252 . Each MIMIC agent instance configured with CoAP acts as a server

    Compatibility with various clients and applications is documented in the section below.

    Back to Top

  3. Installation

    CoAP support is made available in MIMIC as an optional dynamically loadable module. Starting with MIMIC 18.00, you can use the Protocol Wizard to install the CoAP module. If you prefer to enable CoAP by hand, you need to do the following:

    • Use File->Terminate to stop the any running MIMIC daemon.

    • Copy the CoAP shared library (coap.dll on Windows, coap.so on Unix) from "bin/dynamic/optional" to "bin/dynamic" in the install directory.

    • Install the license keys as detailed in the instructions e-mailed to you.

    • Restart MIMIC. You should see the following type of message in the MIMICLog that confirms that the CoAP module was properly loaded : 
      INFO  - COAP : Loaded protocol from < path-to-DLL >
INFO  - COAP v18.00

    Once CoAP is loaded, any agent instance configured to support the CoAP protocol will be able to respond to requests from clients.

    Back to Top

  4. Using CoAP from MIMICView

    If the CoAP module is enabled, then Agent->Add, Agent->Configure and Agent->Paste dialogs will display COAP as an additional checkbox in the Advanced pane along with the SNMP protocols. On selecting the checkbox a new COAP pane will appear.

    This CoAP configuration pane lets the user configure the parameters for a CoAP session:

    • Primary Port

      This optional parameter specifies the non-encrypted, server UDP port to use. If set to 0, this port is disabled. The default port is 5683.

    • Rule file

      This mandatory parameter specifies the CoAP rule file, to determine the response for each REST command with URI. You will not be able to start the agent unless this parameter is set.

      The rule file is detailed below. You can edit rule files directly.

    • Secure Port

      This optional parameter specifies the DTLS-encrypted, server UDP port to use. If set to 0, this port is disabled.The default port is 5684.

    • Key Store

      This optional parameter specifies the keystore file to use. If the keystore file is not set, the DTLS CoAP agent can not receive encrypted commands because the agent needs the correct key to decrypt encrypted traffic.

    Back to Top

  5. Using CoAP from MIMICShell

    A few new commands and some enhanced old commands can be used from the MIMICShell to control the CoAP functionality. Here is a synopsis:

    • mimic protocol msg COAP get args

      This command lets the user gather the self-defining list of arguments required and their particulars. The parameters are detailed above. A sample exchange for this command would be: 

      mimicsh> mimic protocol msg COAP get args
{{primary_port} {Primary Port} {integer} {} {optional} {5683}}
{{rule} {Rule File} {file} {scripts/coap {{*.rul {coap rule files} {edit yes} {new yes}}}
- both} {mandatory} {}} {{secure_port} {Secure Port} {integer} {} {optional} {5684}}
{{keystore} {Key Store} {file} {config/coap {{*.db {Key store files} {edit yes} {new yes}}}
- both} {optional} {samplekeystore.db}}

    • mimic agent get protocol

      This command lets the user look at the protocols currently configured on the agent. A sample exchange for this command would be: 

        mimicsh> mimic agent get protocol
  snmpv1,snmpv2c,COAP

    • mimic agent set protocol

      This command lets the user change the protocol setting for an agent. A sample exchange for this command would be: 

        mimicsh> mimic agent get protocol
  snmpv1
  mimicsh> mimic agent set protocol snmpv1,COAP
  mimicsh> mimic agent get protocol
  snmpv1,COAP

    • mimic agent protocol msg COAP get config

      This command lets the user get the current argument settings. A sample exchange for this command would be: 

        mimicsh> mimic agent protocol msg COAP get config
  {primary_port=5683} {rule=iot-eclipse-org.rul} {secure_port=0}
  {keystore=samplekeystore.db}

    • mimic agent protocol msg COAP set config [config]

      This command lets the user change the current argument settings of all CoAP sessions for an agent. A sample exchange for this command would be: 

        mimicsh> mimic agent protocol msg COAP get config
  {primary_port=5683} {rule=iot-eclipse-org.rul} {secure_port=0}
  {keystore=samplekeystore.db} 

  mimicsh> mimic agent protocol msg COAP set config \{secure_port=5684\}

  mimicsh>  mimic agent protocol msg COAP get config
  {primary_port=5683} {rule=iot-eclipse-org.rul} {secure_port=5684}
  {keystore=samplekeystore.db} 

  mimicsh> mimic agent protocol msg COAP set config \{rule=ikea-e1526.cfg\}

  mimicsh>  mimic agent protocol msg COAP get config
  {primary_port=5683} {rule=ikea-e1526.cfg} {secure_port=5684} {keystore=samplekeystore.db}

    • mimic agent protocol msg COAP get trace
      mimic agent protocol msg COAP set trace [0 or 1]

      This command lets the user change the CoAP tracing configuration for an agent. A sample exchange would be: 

        mimicsh> mimic agent assign 1

  mimicsh> mimic agent protocol msg COAP get trace
  0
  mimicsh>  mimic agent protocol msg COAP set trace 1

  mimicsh> mimic agent protocol msg COAP get trace
  1
      and the log would show: 

      INFO  01/05.09:42:35 - agent 1 trace enabled for COAP
INFO  01/05.09:42:51 - agent 1 loaded device
INFO  01/05.09:42:51 - COAP[AGT=1]: rules database initialized
INFO  01/05.09:42:51 - COAP [AGT=1]: server started
...

    • mimic protocol msg COAP get stats_hdr
      mimic agent protocol msg COAP get statistics

      Returns CoAP statistics information:

      • a list of statistic headers, and
      • current statistics values for the specified server.

      In order, the statistic values are:

      • Total number of CoAP packets sent.
      • Total number of CoAP packets received.

      A sample exchange for these commands would be: 

        mimicsh> mimic protocol msg COAP get stats_hdr
  {{connect} {Connect}} {{disconnect} {Disconnect}} {{published} {Published}}
  {{pktSnt} {PktSent}} {{pktRcv} {PktRcvd}} {{pktDisc} {PktDisc}} 

  mimicsh> mimic agent protocol msg COAP get statistics
  1 0 18 18 18 0
    Back to Top

  6. Recording CoAP

    7. TBD

    Back to Top

  7. Simulation Configuration

    8. CoAP responses to be returned by the simulated sensor are specified by the rule file(s) loaded into the agent instance.

    Back to Top

    Overview

    The rules database is a ASCII text file and the loader reads and sources any Tcl scripts as associated. The contents of the file are used to initialize data structures that will then be used to return a response string (output) for a given request REST command. In the absence of a match, a CoAP error is returned.

    The rules database is located in the scripts/coap/ directory in the MIMIC directory hierarchy. Any custom Tcl scripts also need to be in this same directory.

    NOTE: rules and script files are cached, and modifications to them will only be reloaded by the parser when the rule file modification time is newer than what is in the cache.

    Back to Top

    Format

    The rules database is made of a series of rule blocks. A rule block must have 1 request_header field and either one response or one response_script field. 

    version = 18.00
rule = {
request_header = GET /15011/9063/
response_script = ikea-e1526.mtcl::generate_key
}
rule = {
request_header = GET /15001/
response = [65536,65537,65538,65539,65540,65541,65542]
}
    Back to Top

    Global Tcl Variables

    Any Tcl procedure invoked will have a predefined set of global variables passed to it which identify the current environment.

    • gCurrentRequest

      This variable holds the POST command data received from the CoAP client.

    Back to Top

  8. Compatibility

    9. Click here for the compatibility document. If you get an error, you need to download the optional update package with the Update Wizard.

    Back to Top
    << Previous Section    Next Section >>