Gateway Firmware User Guide Introduction to Canvas Canvas Device Manager (DM) is an IOT device remote management solution. Click the link below for more details: https://lairdcp.github.io/guides/canvas-system-docs/latest/canvas_overview.html Where to Buy Canvas Device Manager-enabled devices are only available through Ezurio directly. Please contact our Sales department if you’re interested: https://www.ezurio.com/contact White Glove After purchasing a device you’ll be put in contact with a Ezurio team member who will create a Canvas account for your organization and transfer the devices you have ordered from escrow. Once this is complete, we’ll arrange a hands on orientation. The following guide is only intended to supplement the information that will be provided in this meeting. Out of the Box A sub account and user are entered into Canvas as part of the shipping process. Simply log in using the credentials provided to you by Ezurio. UART Command line You can communicate with the MG100 directly over UART. Attach the included micro USB cable to the MG100 and a workstation. Using your preferred terminal emulator, select the correct enumerated serial port (COM port in Windows) with baud 115200. Once logged in, repeatedly hitting tab will show available commands. Commonly used commands The command below will show the settings of the attributes: attr show To set an attribute, the command “set” can be used, for example: attr set shell_session_timeout 5 #this will set shell session timeout to 5 minutes or attr set 41 5 #this will set shell session timeout to 5 minutes using the arguments numeric value For more information on attributes see the following links: https://github.com/LairdCP/Attributes https://github.com/CanvasDM/ble_gateway_dm_firmware/tree/main/components/attributes Filesystem The MG100 and Pinnacle 100 have 1MB internal flash memory. To access the memory, use the “fs” set of commands as follows. To list files: fs ls /lfs1/ To show logs: fs ls /lfs1/logs To read logs: fs cat /lfs1/logs/log.001 Some other available commands are: cd ls mkdir mount pwd read cat rn statvfs trunc write LwM2M Lightweight Machine to Machine (LwM2M) is a protocol developed by the Open Mobile alliance for IOT device management. This protocol is designed to enable communication between a server and a client. Using this protocol allows controlling a device’s firmware updates, reset cycles, and reporting intervals, along with many other functions. All supported devices and functions are defined on the link below: https://technical.openmobilealliance.org/OMNA/LwM2M/LwM2MRegistry.html Commands are issued in the format of <Device type, “Object”>/<Numeric instance of the device starting from 0>/<The “item” or operation being issued> For example if you would like to call the serial number of the MG100 the following command is issued: 3/0/2 This command calls object 3, being “device”, instance 0, item 2, being the serial number. The object 3 .XML linked below defines these items: https://raw.githubusercontent.com/OpenMobileAlliance/lwm2m-registry/prod/3.xml Commands can be “read”, “write”, and “execute”. Asynchronous LWM2M uses asynchronous packet transmission making it a great fit with NBIOT. Registration Lifetime Registration lifetime is the interval (seconds) by which the LWM2M client must perform a registration update. Default setting is 900 seconds at the EdgeIQ server The lower this interval is (e.g., 60 seconds), the less latency for LWM2M gateway commands from the server to the device but uses much more LTE-M data in a given time period The higher this interval is (e.g., 15 minutes), the more latency for LWM2M gateway commands from the server to the device but uses much less LTE-M data in a given time period LEDs Red LED - Turns solid once you get on the cellular network. If disconnected, the LED is off. Green LED - Turns on once connected to device management, or any LWM2M server. If disconnected, the LED is off. Blue LED - Turns on when actively connected by BLE to a DM enabled BT610. The blue LED will flash when the gateway receives and processes a BLE advertisement. BLE Discovery In our MQTT firmware, only the Canvas DM-enabled BT610 is discovered. In our LWM2M firmware, both the BT510 and Canvas-enabled BT610 are discovered. Compile switch CONFIG_LCZ_SENSOR_DM_ONLY Look for this function ad_handler in this file https://github.com/CanvasDM/lcz_sensor_telemetry_app_module/blob/main/src/lcz_sensor_scan.c Firmware updates For firmware updates on LWM2M, files must be served using the CoAP protocol. CoAP is similar to HTTP but uses UDP. Californium offers an example CoAP proxy implementation. You may configure this yourself, or contact Ezurio for help with setup. https://github.com/eclipse-californium/californium Open Source users For open source users, see the linked guide below: https://lairdcp.github.io/guides/mg100-canvas-firmware-docs/1.0/standardmg1002canvas.html Logging To view device “System Logs”: Issue a gateway command to send “/logs” to 27038/0/0 27039 is a custom Lwm2m2 object we created to hold the path to scripts See this URL for the XML defining 27038: https://github.com/CanvasDM/lwm2m_file_system_management_module/tree/281da241a0ad397a1a53272c2fcc494707d9fc59/xml Issue a gateway command to read 27038 to get directory listing Issue a gateway command to read a log file listed in 27038/0/1 list Download from the “Files” tab and view the system log Do not attempt to download the highest numbered file (active log) Executable scripts From the web interface Author a text file script starting with a line containing “#!/zsh” and containing commands, one per line to be executed by the zephyr shell. Lines starting with “#” are treated as comments. Upload the device to the “Files” tab of EdgeIQ Issue a gateway command to transfer the file to the device at “pki_status.sh” Issue a gateway command to write “pki_status.sh” to LWM2M resource 27039/0/0 Issue a gateway command to execute LWM2M resource 27039/0/4 Download the output from the device, download file “pki_status.sh.out” from device Download the “pki_status.sh.out” file from the “Files” tab On the Command prompt On your workstation copy files over the UART to the MG100 using the following command: "mcumgr -c com8 fs upload setup.zsh /lfs1/setup.zsh" Example script: #!zsh attr set mqtt_ble_enable 1 attr set mqtt_first_publish 120 attr set mqtt_publish_rate 60 attr set mqtt_ble_ad_manu_id 375 attr set mqtt_ble_ad_name 'TMW012BT' attr set mqtt_endpoint 'us-east-mydevices-sandbox.azure-devices.net' attr set mqtt_port '8883' attr set mqtt_watchdog 0 attr set mqtt_publish_qos 1 attr set mqtt_peer_verify 2 attr set mqtt_subscribe_qos 1 attr set mqtt_connect_on_request 1 attr set mqtt_transport_secure 1 attr set mqtt_root_only 1 attr set mqtt_clean_session 1 # requires newline after final string. Execute on gateway with the command: zsh /lfs1/setup.zsh Operation is successful on “ok”
