canedge2docs - css electronics

CANedge2 DocsRelease FW 01.06.03

Feb 14, 2022

CONTENTS

0.1 CANedge2 documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10.1.1 About this manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10.1.2 Legal information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

0.2 Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40.2.1 CAN-bus (x2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40.2.2 LIN-bus (x2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40.2.3 Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50.2.4 Real-time clock (RTC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50.2.5 Electrical . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50.2.6 Mechanical . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60.2.7 Connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

0.3 Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80.3.1 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80.3.2 Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90.3.3 Enclosure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110.3.4 SD card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110.3.5 LED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130.3.6 Label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

0.4 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150.4.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150.4.2 Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170.4.3 Real-Time-Clock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200.4.4 Secondary port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210.4.5 CAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220.4.6 LIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430.4.7 Connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

0.5 Device file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500.6 Log file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

0.6.1 Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510.6.2 MDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510.6.3 Generic header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

0.7 Remote access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560.7.1 Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560.7.2 Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560.7.3 Managing devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580.7.4 Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

0.8 Firmware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670.8.1 Firmware download . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670.8.2 Firmware versioning & naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670.8.3 Firmware upgrade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

i

CANedge2 Docs, Release FW 01.06.03

0.1 CANedge2 documentation

0.1.1 About this manual

0.1.1.1 Purpose

This manual describes the functionality of the CANedge2 (firmware 01.06.03) with focus on:

1. Hardware & installation

2. Configuration

3. Firmware upgrade

4. Remote access

This manual does not provide details on available software/API tools.

0.1.1.2 Other documentation

The CANedge1 Intro and CANedge2 Intro provide practical guides for getting started. The intros alsodetail software & API tools that can be used with the CANedge.

0.1.1.3 Notation used

The following notation is used throughout this documentation:

Admonitions

Note: Used to highlight supplementary information

Warning: Used if incorrect use may result in major loss of data and/or time

Danger: Used if incorrect use may result in damage to the device, personal injury or death

Number bases

When relevant, the base of a number is written explicitly as 𝑥𝑦, with 𝑦 as the base.

The following number bases are used throughout this documentation:

• Binary (𝑦 = 2). Example: The binary number 10101010 is written as 101010102

• Decimal (𝑦 = 10). Example: The decimal number 170 is written as 17010

• Hexadecimal (𝑦 = 16). Example: The hexadecimal number 𝐴𝐴 is written as 𝐴𝐴16

The value of a number is the same regardless of the base (e.g. the values in above examples are equal101010102 = 17010 = 𝐴𝐴16). However, it is sometimes more convenient to represent the number using aspecific base.

0.1. CANedge2 documentation 1

https://canlogger.csselectronics.com/canedge-getting-started/ce1/

https://canlogger.csselectronics.com/canedge-getting-started/


0.1.2 Legal information

0.1.2.1 Usage warning

Warning: Carefully review the below usage warning before installing the product

The use of the CANedge device must be done with caution and an understanding of the risks involved.The operation of the device may be dangerous as you may affect the operation and behavior of a CANbus system.

Improper installation or usage of the device can lead to serious malfunction, loss of data, equipmentdamage and physical injury. This is particularly relevant when the device is physically connected toa CAN based application that may be controlled via the CAN bus. In this setup you can potentiallycause an operational change in the system, turn on/off certain modules and functions or change to anunintended mode.

While the device supports a high degree of security in regards to wireless data transfer and over-the-airupdates, it is recommended that these features are used with caution. Incorrect usage of this functionalitycan result in a device being unable to connect to your server. Further, changing transmit messages over-the-air should be done with extreme caution.

The device should only be used by persons who are qualified/trained, understand the risks and understandhow the device interacts with the system in which it is integrated.

0.1.2.2 Terms & conditions

Please refer to our general terms & conditions.

0.1.2.3 Electromagnetic compatibility

The CANedge has been tested in accordance with CE, FCC and IC standards.

Certificates are available in the online documentation.

Wifi enabled CANedge devices include the following pre-certificed wireless module: ATWINC1500U.Note that the ATWINC15x0-MR210UB module has been tested with an external whip antenna with again of 2.2dBi.

The device is in conformity with all provisions of Annex II of Council Directive 2014/30/EU, in its latestamended version, referred to EMC directive.

The device complies with Part 15 of the FCC Rules. Operation is subject to the following two conditions:(1) this device may not cause harmful interference, and (2) this device must accept any interferencereceived, including interference that may cause undesired operation.

The device complies with the requirements set forth in the Innovation, Science and Economic Develop-ment Canada (ISED) Rules and Regulations ICES-003 Class B and the measurement procedure accordingto CAN/CSA CISPR 22-10.

Specifically, it is in conformity with the following standards:

EN 55032:2015 - Electromagnetic Compatibility of Multimedia EquipmentEN 55024:2010+A1:2015 - IT equipment. Immunity characteristics. Limits and methods of␣→˓measurementFCC Rules and Regulations Part 15 Subpart B: 2018ICES-003: Issue 6 January 2016

2 CONTENTS

https://www.csselectronics.com/screen/terms/language/en

https://www.microchip.com/wwwproducts/en/ATWINC1500


0.1.2.4 Voltage transient tests

The CANedge has passed below ISO 7637-2:2011 tests, performed by TÜV SÜD:

ISO 7637-2:2011: Voltage transient emissions test on supply linesISO 7637-2:2011: Transient immunity test on supply lines

0.1.2.5 Contact details

For any questions regarding our products, please contact us:

CSS ElectronicsEU VAT ID: DK36711949Soeren Frichs Vej 38K (Office 35), 8230 Aabyhoej, Denmarkcontact[AT]csselectronics.com+45 91252563www.csselectronics.com

0.1. CANedge2 documentation 3

https://www.csselectronics.com


0.2 Specification

0.2.1 CAN-bus (x2)

• Physical

– Two physical CAN-bus interfaces

– Industry standard DB9 (D-sub9) connectors

• Transceiver

– Compliant with CAN Protocol Version 2.0 Part A, B and ISO 11898-1

– Compliant with ISO CAN FD and Bosch CAN FD

– Ideal passive behavior when unpowered (high impedance / no load)

– Protection: ±16kV HBM ESD, ±15kV IEC ESD, ±70 V bus fault, short circuit

– Common mode input voltage: ±30V

– TXD dominant timeout (prevents network blocking in the event of a failure)

– Data rates up to 5Mbps1

• Controller

– Based on MCAN IP from Bosch

– Bit-rate: Auto-detect (from list2), manual simple (from list3) or advanced (bit-timing)

– 128 standard CAN ID + 64 extended CAN ID filters (per interface)

– Advanced filter configuration: Range, mask, acceptance, rejection, down sampling

– Configurable transmit messages, single shot or periodic (up to 128/64 regular/extended)

– Support for Remote-Transmission-Request (RTR) frames

– Silent mode: Restricted (acknowledge only) or monitoring (transmission disabled)

– Supports all CAN based protocols (J1939, CANopen, OBD2, NMEA 2000, . . . )4

• Application

– Control reception (logging) and transmission states using CAN-bus control message

– Heartbeat signal to broadcast device time, space left of SD-card and rx/tx state

0.2.2 LIN-bus (x2)

• Physical

– Two physical LIN-bus interfaces

– Industry standard DB9 (D-sub9) connectors

– No internal diode and resistor for publishing mode

• Transceiver

– Protection: ±8kV HBM ESD, ±1.5kV CDM, ±58V bus fault

– Supports 4V to 24V applications

– TXD dominant timeout (prevents network blocking in the event of a failure)1 Supported FD bit-rates: 1M, 2M, 4M2 Bit-rate list: 5k, 10k, 20k, 33.333k, 47.619k, 50k, 83.333k, 95.238k, 100k, 125k, 250k, 500k, 800k, 1M3 Bit-rate list: 5k, 10k, 20k, 33.333k, 47.619k, 50k, 83.333k, 95.238k, 100k, 125k, 250k, 500k, 800k, 1M, 2M, 4M4 The device logs raw data frames

4 CONTENTS


– Data rates up to 20kbps

• Controller

– Support for both publisher and subscriber modes

– Automatic5 and custom frame lengths

– Classic and Extended checksum formats

– Configurable transmit messages, single shot or periodic

0.2.3 Logging

• Extractable industry grade micro SD-card (8-32GB)

• Standard FAT file system (can be read directly by a PC)

• Logging to industry standard .MF4 (ASAM MDF4) file format

• Simultaneous logging from 2 x CAN-bus + 2 x LIN-bus

• Message time stamping with 50 us resolution

• Supports cyclic logging mode (oldest log file is deleted when memory is full)

• Log file splitting based on file size or time

• Session number (power cycle) log file naming (groups log files)

• Globally unique ID for each device ensures unique log file naming

• Power safe (device can be disconnected during logging without corrupting data)

• High-performance logging6

0.2.4 Real-time clock (RTC)

• High precision real-time clock retains date and time when device is off

• For WiFi-enabled devices, the real-time clock can be synced with an NTP time server

0.2.5 Electrical

• Device supply

– Channel 1 voltage supply range: +7.0V to +32V DC7

– Reverse voltage protection8

– Transient voltage event protection on supply lines9

– Consumption:

∗ CANedge1: 0.8W

∗ CANedge2: 1W

• Secondary port output supply10

5 Data lengths are defined by bits 4 and 5 of the LIN identifier6 See the performance tests7 The device is supplied from connector 1 (CH1)8 Up to 24V9 The transient voltage protection is designed to clamp low energy voltage events. High energy voltage events may

overheat and destroy the input protection10 Can be used to supply external devices

0.2. Specification 5


– Configurable output supply on connector 2 (CH2), fixed 5V up to 1.5A11

– Supports power out scheduling to control the output state based on time of day

0.2.6 Mechanical

• Status indicated using external LEDs

• Robust aluminum enclosure

• Dimensions: 50.2 x 83.4 x 24.5 mm (L x W x H)12

• Weight: 100g

• Operating temperature: -25 degC to +70 degC

0.2.7 Connectivity

• Physical

– SMA connector for external antenna13

– The included dipole antenna has a max gain of 2dBi

• WiFi

– Single-band 2.4 GHz

– Supports IEEE 802.11 b/g/n

– WiFi module certified in USA, Canada, Europe, Japan, Korea, China, India, Taiwan

– Access-point mode

∗ Configurable SSID

∗ Supports WPA/WPA2 security

∗ Supports one connected device at a time

– Station mode (connects to an access-point)

∗ Supports “open” and WPA/WPA2 security settings

∗ Configurable prioritized list of 1-5 WiFi access points

• Services

– Automatic time synchronization14

– Device identification using globally unique device ID

• Security

– Secure file transfer using TLS 1.2 (S3 mode only)

– Credentials stored on the device can be encrypted

• File transfer

– S3

∗ HTTP/HTTPS file transfer11 The 5V output can be used to power WiFi hotspots, sensors, small actuators, external LEDs, etc.12 Without external antenna13 See the installation section for details on e.g. exchanging the antenna14 Requires access to a time server

6 CONTENTS


∗ S3 transfer protocol1516

∗ Log files automatically pushed to server

∗ OTA firmware updates (no need for proprietary software)

∗ OTA configuration updates (no need for proprietary software)

– Web server

∗ HTTP file transfer

∗ Log files can be downloaded from device

15 Open S3 API allows automated management of server objects16 Can be used with Amazon Web Services S3, Google Cloud, Microsoft Azure (via gateway) and several self-hosted

open source solutions

0.2. Specification 7


0.3 Hardware

0.3.1 Installation

This section outlines the installation requirements that shall be satisfied.

0.3.1.1 Supply quality

The nominal voltage shall be kept within specifications at all times. The device is internally protectedagainst low energy voltage events which can be expected as a result of supply wire noise, ESD andstub-wire inductance.

If the supply line is shared with inductive loads, care should be taken to ensure high energy voltage eventsdo not reach the device. Automotive environments often include several sources of electrical hazards,such as load dumps (disconnection of battery while charging), relay contacts, solenoids, alternator, fuelinjectors etc. The internal protection circuitry of the device is not capable of handling high energyvoltage events directly from such sources.

0.3.1.2 Grounding

ISO 11898-2 tolerates some level of ground offset between nodes. To ensure the offset remains withinrange, it is recommended to use a single point ground reference for all nodes connected to the CAN-bus.This may require the ground wire to be carried along with data wires.

If a secondary CAN-bus network is connected to Channel 2, care must be taken to ensure that the groundpotentials of the two networks can safely be connected through the common ground in the device.

0.3.1.3 Cable shielding

Shielding is not needed in all applications. If shielding is used, it is recommended that a short pig-tailbe crimped to the shield end at each connector.

0.3.1.4 CAN ISO 11898-2

ISO 11898-2 defines the basic physical requirements of a high-speed CAN-bus network. Some of theseare listed below:

• Max line length (determined by bit-rate)

• Line termination (120 ohm line termination at each end of data line)

• Twisted data lines

• Ground offsets in range -2V to +7V

0.3.1.5 CAN-bus stub length

It is recommended that the CAN-bus stub length is kept short. The stub length is defined as the lengthfrom the ”main” data line wires to the connection point of the CAN-bus nodes.

0.3.1.6 Enclosure caution

The device is not intended for use without the enclosure.

8 CONTENTS


Warning: Opening the enclosure can permanently damage the device due to e.g. ESD (electrostaticdischarge) - and improper handling may void the warranty

0.3.1.7 Mounting

The device should be mounted in a way that minimizes vibration exposure and accounts for the IP ratingof the device.

0.3.1.8 Antenna

The device uses an external WiFi antenna. The antenna satisfies the constraints under which thecontained WiFi module has been tested - in particular, it has a max gain of 2dBi. The antenna can bereplaced or extended.

If you need to re-orient, disconnect, re-connect or tighten the antenna, you should use the proper tight-ening mechanism. Specifically, you should not directly turn the antenna (as this may loosen the internalconnection to the PCB) - rather, you should first loosen the nut, after which you can e.g. re-orient theantenna and then re-tighten the nut.

It is critical that the antenna is properly connected at all times and that it is not loose when the CANedgeis powered on. Operation with a loose antenna or without the antenna entirely can damage the device.

0.3.2 Connector

0.3.2.1 Pinout

The CANedge uses two D-sub9 connectors for supply, 2 x CAN, 2 x LIN and a 5 V Supply Output.

Make sure to refer to the pinout matching the product hardware revision (see the label).

0.3. Hardware 9


Hardware revision ≥ 00.01

Pin # Channel 1 (CH1) Channel 2 (CH2)1 NC 5V Supply Output2 CAN 1 L CAN 2 L3 GND GND4 LIN Data 1 LIN Data 25 NC NC6 GND (optional) GND (optional)7 CAN 1 H CAN 2 H8 NC NC9 Supply & LIN1 VBAT LIN2 VBAT

Hardware revision = 00.00

The hardware 00.00 pinout can be found here.

Supply

The supply (CH1 pin 9) is used to power the device. The supply is internally protected against reversepolarity and low-energy voltage spikes.

Refer to the Electrical Specification for more details on the device supply.

Warning: The supply line must be protected against high-energy voltage events exceeding devicelimits

GND

All GND (ground) pins are connected internally.

5 V Supply Output

The +5 V output can be used to power external devices. The power can be toggled via the deviceconfiguration. The output can deliver 1.5 A @ 5 V continuously.

Danger: Connecting external input power to this pin can permanently damage the device

Warning: External protection (such as clamp diodes) must be installed if inductive loads areconnected to the 5V Supply Output

CAN L/H

Warning: CAN-bus requires no common reference (ground). However, it is recommended thatGND (ground) is carried along with CAN-L/H to prevent that the common-mode voltage is exceeded(resulting in transceiver damage)

10 CONTENTS


LIN VBAT

The LIN-bus positive reference. Supports systems operating from 4V to 24V.

• LIN1 VBAT: Pin is shared with device supply and shares the supply input protection circuit

• LIN2 VBAT: Tolerates voltage spikes up to 48V. Spikes above this can damage the interface

LIN Data

LIN-bus single-wire data line referenced to LIN VBAT.

0.3.2.2 Basic wiring example

Below example illustrates how the CANedge CAN-bus 1 (channel 1) can be connected.

o--o--------------------o------------ ... ---o-----------o CAN 1 H (pin 7)| | | | |

+++ | | | +++|R| | | | |R|+++ | | | +++| | | | |o-----------o--------------------o--- ... ------------o--o CAN 1 L (pin 2)

|CANedge | | Node 1 | | Node N |+--+--------+--+ +--+--------+--+ +--+--------+--+| CANH CANL| | CANH CANL| | CANH CANL|| | | | | || Supply GND | | Supply GND | | Supply GND |+--+--------+--+ +--+--------+--+ ... +--+--------+--+

| | | | | |o--------------------o------------ ... ---o-----------o SUPPLY (pin 9)

| | |o--------------------o--- ... ------------o--o GND (pin 3)

0.3.3 Enclosure

The CANedge uses a robust aluminium enclosure - PDF drawings and 3D STEP files can be found inthe online documentation.

0.3.4 SD card

The CANedge uses an extractable SD-card to store device configuration and log files.

Warning: Never extract the SD-card while the device is on. Remove power first and wait a fewseconds for the device to turn off.

0.3.4.1 File organization

The files stored on the SD-card are organized as illustrated by below example:

/config-XX.XX.jsonschema-XX.XX.jsondevice.json

(continues on next page)

0.3. Hardware 11


(continued from previous page)

LOG/[DEVICE_ID]

0000000100000001.MF400000002.MF4......

0000000200000001.MF400000002.MF4......

...

...

• config-XX.XX.json: Configuration File (device configuration)

• schema-XX.XX.json: Rule Schema (configuration rules)

• device.json: Device File (device information)

• LOG/: Path for log files

For more information on the specific files, refer to the documentation menu.

Log files

Log files are stored in LOG/[DEVICE_ID]/[SESSION_NUMBER]/[SPLIT_NUMBER].[FILE_EXTENSION]. Formore information on the structure of the log files, refer to the log file section.

0.3.4.2 Type

The CANedge uses a specifically selected industrial graded SD-card with special timing constraints toensure safe shutdown when power is lost.

Warning: The device cannot be guaranteed to work if the pre-installed SD-card is replaced

Exchanging SD cards between devices

The SD card is not “locked” to the device. If the card is replaced, be aware of the following points:

• Critical device specific data are not stored on the SD card (e.g. device ID)

• Non-critical meta data are stored on the SD card (e.g. log file session number)

• If the card is replaced by a card from another device, it is recommended to clear the card first

• It may be necessary to update the configuration file if it contains device specific settings

0.3.4.3 Lifetime

The SD-card memory wears as any other flash based memory. The industrial graded SD-cards providedwith the CANedge have the following guaranteed minimum endurance numbers1:

1 TBW: Terabytes Written

12 CONTENTS


Size [GB] TBW Lifetime @ 1MB/sec [years]2 Lifetime @ 1MB/min [years]8 24 0.8 47.932 96 3.2 191.5

0.3.5 LED

0.3.5.1 Location

The LEDs are located at the back of the device as illustrated below.

0.3.5.2 Overview

LED Short Name LED Color Main FunctionPWR Green PowerCH1 Yellow Bus activity on connector 1

(CH1)CH2 Yellow Bus activity on connector 2

(CH2)MEM Red Memory card activityWFI Blue WiFi connected

PWR

The Power LED is constantly on when the device is in normal operation. An exception is when thefirmware is being updated (for more information go to the Firmware section).

CH1 / CH2

The Channel 1 / Channel 2 LEDs indicate bus activity on Channel 1 and 2 respectively.

MEM

The Memory LED indicates activity on the memory card. Config file parsing, message logging, fileupload etc. all generate activity on the memory card.

2 A constant logging rate of 1 MB/sec is likely much much higher than in any practical logging use-case

0.3. Hardware 13


WFI

The WiFi LED is on when the device is connected to a WiFi access point.

Note: The device only connects to WiFi when a transfer is pending and is otherwise disconnected(LED off)

0.3.6 Label

A unique label is attached to the back of each device. Examples of the labels are illustrated below.

Note: The data matrix can be scanned to simplify installation of a new device

The label holds the following information:

• Device type: CANedge2

• Production data in format YYYYWW (WW = week number): 201930

• Hardware version: 00.00

• Unique device ID: EA9B650D

• Data matrix (ECC200) containing production date, device ID and the WiFi MAC address: 201930;EA9B650D;F8F005E40ED6

• FCC ID of internal WiFi controller: 2ADHKATWINC1500U

14 CONTENTS


0.4 Configuration

0.4.1 General

This page documents the general configuration.

0.4.1.1 Configuration file fields

This section is autogenerated from the Rule Schema.

Device general.device

Meta data general.device.meta

Optional meta data string. Displayed in device file and log file headers. Example: Site1; Truck4; Confi-gRev12

Type Min length Max lengthstring 0 30

Security general.security

Server public key general.security.kpub

Server / user ECC public key in base64 format. Shall match the encryption used for all protected fields.


Debug general.debug

Debug functionality for use during installation and troubleshooting.

System log general.debug.syslog

System events logged to the SD-card. The log levels are listed in order of increasing amount of informationlogged. Should only be enabled if needed during installation or troubleshooting.

Type Default Optionsinteger 0 Disable (0): 0 Error (1): 1 Warning (2): 2 Info (3): 3

0.4.1.2 Configuration explained

This section contains additional information and examples.

Device meta data

The device meta data is an optional string copied to the device.json file and log file headers.

Security

Some configuration field values can be encrypted to hide sensitive data stored in the Configuration File(passwords etc.). In this section, we provide a technical summary and provide resource suggestions forimplementing the encryption.

The field encryption feature uses a key agreement scheme based on Elliptic Curve Cryptography (ECC)(similar to the one used in a TLS handshake). The scheme allows the device and user to compute

0.4. Configuration 15


the same shared secret, without exposing any secrets. The shared secret is in turn used to generate asymmetric key, which is used to encrypt / decrypt protected field values.

The following sequence diagram illustrates the process of encrypting configuration fields:

Below we explain the sequence:

1. Load device public key field (kpub) from the device.json file

2. Decode the device public key (base64)

3. Generate random user key pair (public and private) using curve secp256r1

4. Calculate shared secret using device public key and user private key

5. Derive shared symmetric key using HMAC-SHA256 with “config” as data and shared secret as key.Use the first 16 bytes of the output

6. Encode user public key (used by the device to calculate the same shared symmetric key for decryp-tion)

7. Set the encoded user public key in the device configuration file

8. Use AES-128 CTR to encrypt protected fields using the symmetric key. The resulting initializationvector (iv) and cipher text (ct) are concatenated (iv + ct), base64 encoded and stored in the

16 CONTENTS


configuration file

Note: The symmetric key shall match the public key set by the user in the configuration and protectedfields shall be encrypted with this symmetric key

Note: By storing the symmetric key it is possible to change specific protected fields - without updatingthe user public key (and in turn all other protected fields)

Encryption tools

Tools are provided with the CANedge for use in encrypting secure fields - see the CANedge Intro.

Example Python code

You can batch-encrypt passwords across multiple devices using e.g. Python. Below we provide a basiccode sample to illustrate how Python can be used to encrypt plain-text data. The example code is testedwith Python 3.7.2 and requires the pycryptodome crypto library:

Python example code

0.4.2 Logging

This page documents the logging configuration


This section is autogenerated from the Rule Schema file.

File log.file

File split size (1 to 512 MB) log.file.split_size

Log file split size in MB. When the file split size is reached a new file is created and the logging continues.Closed log files can be pushed to a server if WiFi is available. Small split sizes may reduce performance.

Type Default Minimum Maximuminteger 50 1 512

File split time period (0 to 86400 seconds, 0 = disable) log.file.split_time_period

Log file split time period in seconds relative to midnight (00:00:00). When a split time is reached a newfile is created and the logging continues. Closed log files can be pushed to a server if WiFi is available.Small split time periods may reduce performance.

Type Default Minimum Maximum Multiple ofinteger 0 0 86400 10

File split time offset (0 to 86400 seconds) log.file.split_time_offset

Log file split time offset in seconds. This value offsets the split_time_period relative to midnight(00:00:00). The set value shall be less than the split_time_period value.

Type Default Minimum Maximum Multiple ofinteger 0 0 86400 10



Cyclic logging log.file.cyclic

With cycling logging mode enabled the oldest log file is deleted when the memory card becomes full,allowing the logging to continue.

Type Default Optionsinteger 1 Disable: 0 Enable: 1

Compression log.compression

Level log.compression.level

Window size used during optional compression. Larger window sizes yield potentially better compres-sion rates, but may reduce logging performance. Compressed log files need to be decompressed prior toprocessing.

Type De-fault

Options

inte-ger

0 Disable: 0 256 bytes window: 256 512 bytes window: 512 1024 bytes window:1024

Encryption log.encryption

State log.encryption.state

Optional log file encryption. Encrypted log files need to be decrypted prior to processing. Decryptionrequires your encryption password in plain form - if this is lost, the encrypted data cannot be recovered.


Error Frames log.error_frames

State log.error_frames.state

Specify whether to record error frames. Enabling this can negatively impact performance, as a potentiallylarge number of additional frames may be recorded.




File split

File splitting can be based on file size or file size and time:

• split_time_period = 0: Split based on size only

• split_time_period > 0: Split based on both size and time - whichever is reached first

Limits

The file system limits should be considered when configuring the split size and time:

• SD-card size

18 CONTENTS


• Max 1024 sessions

• Max 256 splits (log files) in each session

Above limits result in a maximum of 1024*256=262144 log files if fully utilised.

If the session count limit is reached, the logger will either:

• Stop logging if cyclic logging is disabled1

• Delete the oldest session if cyclic logging is enabled

If SD-card becomes full (no more space), the logger will either:

• Stop logging if cyclic logging is disabled1

• Delete the oldest split file from the oldest session if cyclic logging is enabled

Compression

Log files can be compressed on the device during logging using a variant of the LZSS algorithm based onheatshrink. Compressed files will have *.MFC as file extension. A high window size improves compressionrates, but may cause message loss on very busy networks.

The table below lists results for J1939 and OBD data with different window size configurations3:

Window size (bytes) J1939 % (range) OBD % (range)256 49.7 (47.1-51.4) 32.0 (30.3-32.8)512 49.5 (46.3-51.6) 30.2 (29.6-31.1)1024 41.4 (38.9-45.5) 30.0 (29.6-30.8)

Decompression can be done using an implementation of LZSS or via the CANedge tools (see the CANedgeIntro).

Note: The split size set in split_size considers the size of the compressed data. I.e. if the split sizeis 10 MB, the resulting file sizes become 10 MB regardless if compression is used or not.

Encryption

Log files can be encrypted on the device. Here, data is streamed through an AES-GCM encryptionscheme prior to persistence on the SD card. Encrypted files have *.MFE as file extension.

Note: It is recommended to use a 40+ character password for proper encryption

Decryption can be done using an implementation of the PBKDF2 algorithm or via CANedge tools (seethe CANedge Intro).

Error Frames

Enabling error frames will log errors across all interfaces, both CAN and LIN. Note that this can decreasethe performance of the device due to the added logging load.

1 If files are offloaded through WiFi in the case of the CANedge2, the logging will resume3 Compressed size in percentage of original. Lower is better.


https://github.com/atomicobject/heatshrink


0.4.3 Real-Time-Clock

This page documents the real-time-clock configuration



Real-Time Clock (RTC) rtc

Time synchronization method rtc.sync

Internal real-time-clock synchronization method. The real-time-clock is maintained when the device isoff.

Type Default Optionsinteger 2 Retain current time: 0 Manual update: 1 Automatic update (requires WiFi): 2

Time zone (UTC-12 to UTC+14) rtc.timezone

Adjustment in full hours to the UTC time. Includes daylight savings time if applicable.

Type Default Minimum Maximuminteger 0 -12 14

Adjustment (-129600 to 129600 seconds) rtc.adjustment

Adjustment in seconds to the UTC time. Can be used for fine tuning the internal time.

Type Default Minimum Maximuminteger 0 -129600 129600



The CANedge uses a real-time clock (RTC) with battery backup, which allows it to retain the absolutedate & time when the device is not powered. The RTC enables the CANedge to add absolute timestampsto recorded messages. The RTC is set to UTC time during production.

Time-zone changes and minor adjustments can be done via the timezone and adjustment fields.

Synchronization methods (sync)

The RTC time can either be retained, manually set or automatically synchronized.

Manual update

Manually changing the RTC is only needed if the RTC time is completely lost (e.g. after a batteryreplacement). The following sequence explains how the RTC can be manually set:

1. Select the manual ´sync´ method and set the current UTC time

2. Power on the device and wait a few seconds to allow the device to read the manually set time

3. Power off the device

4. Change the ´sync´ method to retain current time

20 CONTENTS


5. Power on the device again

6. Verify that the new absolute time is now correctly retained across power cycles

7. Set timezone (timezone) and do minor adjustments (adjustment) if needed

Automatic update

The CANedge2 supports auto RTC synchronization via WiFi (enabled by default). In this mode, thedevice retains the current time - but periodically synchronizes the RTC against an NTP server.

Warning: The device relies on a correct RTC as part of the S3 server communication

0.4.4 Secondary port

This page documents the secondary port configuration



Power schedule secondaryport.power_schedule

The daily power schedule is defined by a number of power-on from/to intervals. Define no power-onintervals to keep always off. Define one interval with from/to both set to 00:00 to keep always on. Timeformat is HH:MM (1 minute resolution)

Type Default Max itemsarray [] 5

Item secondaryport.power_schedule.item

From secondaryport.power_schedule.item.from

Power-on FROM time in format HH:MM. Shall be before power-on TO time. E.g. at midnight 00:00

Type Defaultstring 00:00

To secondaryport.power_schedule.item.to

Power-on TO time in format HH:MM. Shall be after power-on FROM time. E.g. at midday 12:00.

Type Defaultstring 00:00



Note: Power out scheduling has resolution of 1 min and 1 min tolerance



Note: Power out scheduling uses adjusted local time (as set in the configuration)

Example: Secondary port power is scheduled to be on daily in the interval 00:00-04:00 and12:00-16:00. Secodary port configuration:

"secondaryport": {"power_schedule": [{

"from": "00:00","to": "04:00"

},{

"from": "12:00","to": "16:00"

}]

}

The power out is turned off when the time changes from 03:59 to 04:00 and 15:59 to 16:00.

0.4.5 CAN

This page documents the CAN configuration.

The configuration of CAN Channel 1 and CAN Channel 2 is identical.

The CAN configuration is split into the following sections:

0.4.5.1 General

This page documents the general configuration

Configuration file fields


General can.general

CAN bus general configuration

Reception (rx) initial state can.general.rx_state

The initial state of CAN-bus reception. Can be changed using the control signal.


Transmission (tx) initial state can.general.tx_state

The initial state of CAN-bus transmissions. Can be changed using the control signal.


Configuration explained


22 CONTENTS


0.4.5.2 Physical

This page documents the physical configuration



Mode can.phy.mode

Device CAN bus mode. Configures how the device interacts with the bus. In Normal mode, the device canreceive, acknowledge and transmit frames. In Restricted mode, the device can receive and acknowledge,but not transmit frames. In Bus Monitoring mode, the device can receive, but not acknowledge or transmitframes. It is recommended to always use the most restrictive mode possible.

Type De-fault

Options

inte-ger

1 Normal (receive, acknowledge and transmit): 0 Restricted (receive and acknowledge):1 Monitoring (receive only): 2

Automatic retransmission can.phy.retransmission

Retransmission of frames that have lost arbitration or that have been disturbed by errors during trans-mission.


CAN FD specification can.phy.fd_spec

Configures the CAN FD specification used by the device. Shall match the specification used by the CANbus network.

Type Default Optionsinteger 0 ISO CAN FD (11898-1): 0 non-ISO CAN FD (Bosch V1.0.): 1

Bit-rate configuration mode can.phy.bit_rate_cfg_mode

Configures how the CAN bus bit-rate is set. Modes Auto-detect and Bit-rate support all standard bit-rates.Non-standard bit-rate configuration can be set using Bit-timing. It is recommended to set the bit-ratemanually if it is known.

Type Default Optionsinteger 0 Auto-detect: 0 Bit-rate (simple): 1 Bit-timing (advanced): 2



Bit-rate configuration

The input clock to the CAN-bus controllers is set to 40MHz (480MHz prescaled by 12).

Bit-rate modes Auto-detect and Bit-rate (simple) support the following list of bit-rates1:1 All bit-rate configurations use a sample point (SP) of 80%



Bitrate BRP Quanta Seg1 Seg2 SJW5k 100 80 63 16 410k 50 80 63 16 420k 25 80 63 16 433.333k 10 120 95 24 447.619k 8 105 83 21 450k 10 80 63 16 483.333k 4 120 95 24 495.238k 4 105 83 21 4100k 5 80 63 16 4125k 4 80 63 16 4250k 2 80 63 16 4500k 1 80 63 16 4800k 1 50 39 10 41M 1 40 31 8 42M 1 20 15 4 44M 1 10 7 2 2

In Auto-detect mode, the device will attempt to determine the bit-rate from the list of detectable bit-rates. Depending on factors such as data patterns, bit-rate deviation etc. it may not always be possibleto detect the bit-rate automatically.

Warning: It is recommended to set the bit-rate manually when possible

Warning: Bit-rate auto-detect cannot be used to detect a CAN FD switched bit-rate

In mode Bit-timing (advanced), the bit-rate timing can be set directly. The following equations canbe used to calculate the bit-timing fields:

• Input clock: 𝐶𝐿𝐾 = 48000000012 = 40000000 = 40MHz

• Quanta: 𝑄 = 1 + 𝑆𝐸𝐺1 + 𝑆𝐸𝐺2

• Bit-rate: 𝐵𝑅 = 𝐶𝐿𝐾/𝐵𝑅𝑃𝑄

• Sample point: 𝑆𝑃 = 100 · 1+𝑆𝐸𝐺1𝑄

Example: Matching bit-timing settings based on different input clock frequency (CLK).

Settings to match (based on a 80MHz input clock):

• Bit-rate: 2M

• Quanta: 40

• SEG1: 29

• SEG2: 10

• Sample point: 75%

Above settings are based on an input clock with frequency:

𝐶𝐿𝐾 = 𝐵𝑅 · 𝑄 = 2000000 · 40 = 80MHz

The CANedge uses a 40MHz input clock. To obtain a bit-rate of 2M with a 40MHz input clock, thenumber of quanta is calculated as:

𝑄 = 𝐶𝐿𝐾/𝐵𝑅𝑃

𝐵𝑅= 40000000/1

2000000 = 20

24 CONTENTS


To obtain a sampling point of 75%, SEG1 is calcualted as:

𝑆𝐸𝐺1 = 𝑆𝑃 · 𝑄

100 − 1 = 75 · 20100 = 14

Now, SEG2 is calculated as:

𝑆𝐸𝐺2 = 𝑄 − 𝑆𝐸𝐺1 − 1 = 20 − 14 − 1 = 5

The equivalent bit-timing settings using the 40 MHz input clock of the CANedge becomes:

• BRP: 1

• SEG1: 14

• SEG2: 5

0.4.5.3 Filter

This page documents the filter configuration



Receive filters can.filter

Filter remote request frames can.filter.remote_frames

Controls if remote request frames are forwarded to the message filters. If ‘Reject‘ is selected, remoterequest frames are discarded before they reach the message filters.

Type Default Optionsinteger 0 Reject: 0 Accept: 1

ID filters can.filter.id

Filters are checked sequentially, execution stops with the first matching filter element. Max 128 11-bitfilters and 64 29-bit filters.

Type Min items Max itemsarray 1 192

Item can.filter.id.item

Name can.filter.id.item.name

Optional filter name.

Type Max lengthstring 16

State can.filter.id.item.state

Disabled filters are ignored.


Type can.filter.id.item.type



Action on match, accept or reject message.

Type Default Optionsinteger 0 Acceptance: 0 Rejection: 1

ID format can.filter.id.item.id_format

Filter ID format. Filters apply to messages with matching ID format.

Type Default Optionsinteger 0 Standard (11-bit): 0 Extended (29-bit): 1

Filter method can.filter.id.item.method

The filter ID matching mechanism.

Type Default Optionsinteger 0 Range: 0 Mask: 1

From (range) / ID (mask) (HEX) can.filter.id.item.f1

If filter method is Range, this field defines the start of range. If filter method is Mask, this field definesthe filter ID.

Type Default Max lengthstring 0 8

To (range) / mask (mask) (HEX) can.filter.id.item.f2

If filter method is Range, this field defines the end of range. If filter method is Mask, this field definesthe filter mask.

Type Default Max lengthstring 7FF 8



The following uses a mix of binary, decimal and hexadecimal number bases. For more information onthe notation used, refer to section Number bases.

Note: In the following, it is convenient to do some calculations using binary numbers (base 2). However,the configuration file generally accepts either decimal or hexadecimal numbers.

Filter processing

The filter elements in the list of filters are processed sequentially starting from the first element. Pro-cessing stops on the first filter match.

Example: A message matches filter element 3. Filter element 4 is not evaluated.

26 CONTENTS


Messages matching no filters are rejected as default. Note that the default Configuration File has filtersthat accept all incoming CAN messages (both standard/extended CAN IDs).

Filter state

The state of filter elements can be Enable or Disable. Disabled filter elements are ignored, as if they arenot in the list of filters. If there are no enabled filters in the list then all messages are rejected.

By disabling a filter element (instead of deleting the element) it can be easily enabled at a later time.

Filter types

Filter elements can be either Acceptance or Rejection:

• If a message passes an Acceptance filter it is accepted

• If a message passes a Rejection filter it is discarded

• If a message does not pass a filter, the next filter in the list is processed

The filter list can hold a combination of Acceptance and Rejection filter elements. The first matchingfilter element determines if a message is accepted or rejected. Acceptance and Rejection filters can becombined to generate a complex message filtering mechanism.

Example: A message matches acceptance filter 3. Rejection filter 4 is not evaluated. The message isaccepted.

Example: A message matches rejection filter 2. The following filters are not evaluated. The message isrejected.

Example: A message does not match any filters. The message is rejected.

Filter method

Acceptance and Rejection filters can be defined by range or mask. In either case, both the message type(standard / extended) and ID are compared to the filter.

Filter range method

With the Range method, the filter defines a range of IDs which are compared to the message ID. MessageIDs within the range (both start and end included) pass the filter.

Example: Standard ID filter with range from = 1, to = 10:



ID format ID (DEC) PassStandard 0 NoStandard 1 YesStandard 10 YesStandard 11 NoExtended 1 No

Filter mask method

With the Mask method, the filter defines an ID and Mask which are compared to the message ID.

A message passes a mask filter if the following condition is true1:

filter_id & filter_mask == message_id & filter_mask

Below a few examples to demonstrate the use of filters.

Example: Filter configuration which accepts one specific message ID: 2000 * 10 = 111110100002. Thefilter ID is set to the value of the message ID to accept. The filter mask is set to all ones, such that allbits of the filter are considered, as given in (1).

Filter IDFilter maskMasked filter

111110100002&111111111112

111110100002

(1)Message IDFilter maskMasked ID

111110100002&111111111112

111110100002

(2)

To test if the message passes the filter, we apply the filter mask to the message ID as given in (2). Themasked filter and the masked ID are equal - the message passes the filter.

Example: Filter configuration which accepts two message IDs:

• 200010 = 111110100002

• 200110 = 111110100012

Note that the two binary numbers are identical except for the rightmost bit. To design a filter whichaccepts both IDs, we can use the mask field to mask out the rightmost bit - such that it is not consideredwhen the filter is applied. In (1) the mask is set such that the rightmost bit is not considered (indicatedby red color).

Filter IDFilter maskMasked filter

111110100002&111111111102

111110100002

(1)Message IDFilter maskMasked ID

111110100012&111111111102

111110100002

(2)

To test if the messages pass the filter, we apply the mask to the message ID 111110100012 as given in(2). The masked filter and the masked ID are equal - the message passes the filter. Note that both111110100002 and 111110100012 passes the filter, as the rightmost bit is not considered by the filter (therightmost bit is masked out).

Example: J1939 - filter configuration which accepts PGN 61444 (EEC1) messages.

J1939 message frames use 29-bit CAN-IDs. The Parameter Group Number (PGN) is defined by 18 ofthe 29 bits. The remaining 11 bits define the priority and source address of the message. It is oftenuseful to configure a filter to accept a specific PGN regardless of the source address and the priority -this can be done using the filter mask (to ignore the source and priority).

Below, the left red bits represent the 3-bit priority, the green bits the 18-bit PGN and the right red bitsthe 8-bit source address of the 29-bit CAN-ID.

000111111111111111111000000002 = 3FFFF0016

1 & is used as the bitwise AND operation

28 CONTENTS


Message ID bits in positions with zero bits in the filter mask are ignored. By using 3FFFF0016 as filtermask, the source and priority are ignored.

To specifically accept PGN 61444 F00416 messages, the message ID is set to F0040016 - note the thefinal 8-bit 0016 represents the source address which is ignored by the filter mask (these bits can be setto any value).

Filter mask 3FFFF0016 can be used for all J1939 PGN messages. To accept specific PGNs, the messageID is adjusted. To accept one specific PGN (as in the example above), the message ID is set to thespecific PGN with 0016 appended to represent the ignored source address field.

Filter list examples

Below examples demonstrate how filters can be combined into a list of filters.

Example: The filter list is setup to accept standard messages with even IDs in range 50010 − 100010(500, 502, . . . 998, 1000):

The following two filters are used to construct the wanted filter mechanism:

• Rejection filter which rejects all odd message IDs

• Acceptance filter which accepts all message IDs in range 50010 − 100010

The rejection filter is setup to reject all odd messages by using Mask filtering. The filter issetup with:

• Filter ID: 110 = 000000000012

• Filter Mask: 110 = 000000000012

Above rejection filter rejects all messages with the rightmost bit set (all odd IDs).

The acceptance filter is setup to accept all messages in range 50010 − 100010 by using Rangefiltering. The filter is setup with:

• Filter from: 50010

• Filter to: 100010

The filter list is constructed with the rejection filter first, followed by the acceptance filter.

Note that messages are first processed by the rejection filter (rejects all odd messages), thenproccessed by the acceptance filter (accepts all message in range). If none of the filterspass/match, the default behavior is to reject the message. It is in this case important thatthe rejection filter is placed before the acceptance filter in the list (processing stops on firstmatch).

Filter list test table:

Message ID Filter elm 1 Filter elm 2 Result49810 Ignore Ignore Reject49910 Reject Reject50010 Ignore Accept Accept50110 Reject Reject99910 Reject Reject100010 Ignore Accept Accept100110 Reject Reject100210 Ignore Ignore Reject



Message Prescaling

Message prescaling can be used to decrease the number of logged messages for a given message ID.Prescaling is applied to the messages accepted by the associated filter. The list of filters can be assigneda mixture of prescaler types.

Applying filters can dramatically reduce log file size, resulting in prolonged offline logging and reduceddata transfer time and size.

The prescaling type can be set to:

• None: Disables prescaling

• Count: Prescales based on the number of messages

• Time: Prescales based on message period time

• Data: Prescales based on changes in the message data payload

The first message with a given ID is always accepted regardless of prescaling type.

Note: A maximum of 100 unique message IDs can be prescaled for each CAN-bus channel (the first100 IDs received by the device). Additional unique IDs are not prescaled

Count

Count prescaling reduces the number of messages with a specific ID by a constant factor (prescalingvalue). A prescaling value of 2 accepts every 2nd message (with a specific ID), a value of 3 every 3rdand so on up to 2562.

Count prescaling applied to ID 60010 with a scaling value of 3

ID (DEC) ID occurrences Result60010 1 Accept60010 2 Reject60010 3 Reject60010 4 Accept60010 5 Reject

Time

Time prescaling sets a lower limit on time interval (period time) of a specific message ID. This is doneby rejecting messages until at least the prescaler time has elapsed3. The prescaler timer is reset eachtime a message is accepted. The prescaling value is set in milliseconds4 with a valid range 1-4194304(0x400000).

This prescaler type is e.g. useful if a slowly changing signal (low frequency signal content) is broadcastedon the CAN-bus at a high frequency5.

Example: A slowly changing temperature measurement broadcasted every 10 ms (100Hz). Prescaled toa minimum time interval of 100ms (prescaler value set to 100).

2 A scaling factor of 1 effectively disables prescaling3 Note that messages are not resampled to a specific fixed period time4 It is not possible to do sub-millisecond time prescaling5 Higher frequency than needed to get a good representation of the signal content

30 CONTENTS


Example: Time prescaling applied to ID 70010 with a time interval of 1000ms selected.

ID (DEC) Message timestamp[ms]

Prescaler timer [ms] Result

70010 200 0 Accept70010 700 500 Reject70010 1000 800 Reject70010 1200 1000 -> 0 (reset) Accept70010 1300 100 Reject70010 3200 2000 -> 0 (reset) Accept70010 4200 1000 -> 0 (reset) Accept70010 5200 1000 -> 0 (reset) Accept

Data

Data prescaling can be used to only accept messages when the data payload changes. A mask can beset to only consider changes in one or more specific data bytes. The mask works on a byte level. Themask is entered in hex up to 8 bytes long (16 hex characters). Each byte contains 8 bits, allowing forthe mask to be applied to any of the maximum 64 data bytes (CAN FD).

This prescaler type is useful if only changes in data or parts of the data are to be logged.

Examples of data masks:

• "": A empty mask triggers on any data change (equivalent to mask value FFFFFFFFFFFFFFFF)

• 1: Triggers on changes to the first data byte (binary 1)

• 2: Triggers on changes to the second data byte (binary 10)

• 3: Triggers on changes to the first or second data byte (binary 11)

• 9: Triggers on changes to the first or fourth data byte (binary 1001)

• FF: Triggers on changes to any of the first 8 data bytes (binary 11111111)

• 100: Triggers on changes to the 9th data byte (binary 100000000)

If the data payload contains more data bytes than entered in the mask, then changes to the additionalbytes are ignored by the prescaler.



Warning: Data prescaling assumes that a message with a specific ID always carries the samenumber of data bytes

Example: A discretely changing signal is broadcasted every 100 ms (10Hz). A data prescaler is usedsuch that only changes in the signal are logged.

Example: Data prescaling applied to ID 80010 with empty mask (all changes considered). D0-D3 is a4-byte payload (with D0 the first data byte).

ID (DEC) D0 D1 D2 D3 Result80010 00 11 22 33 Accept80010 00 11 22 33 Reject80010 00 BB 22 33 Accept80010 AA BB 22 33 Accept80010 AA BB 22 DD Accept80010 AA BB 22 DD Reject

Example: Data prescaling applied to ID 80010 with mask 1 (considering only changes to the 1st databyte). D0-D3 is a 4-byte payload (with D0 the first data byte).

ID (DEC) D0 D1 D2 D3 Result80010 00 11 22 33 Accept80010 00 11 22 33 Reject80010 00 BB 22 33 Reject80010 AA BB 22 33 Accept80010 AA BB 22 DD Reject80010 AA BB 22 DD Reject

Example: Data prescaling applied to ID 80010 with mask 8 (considering only changes to the 4th databyte). D0-D3 is a 4-byte payload (with D0 the first data byte).

ID (DEC) D0 D1 D2 D3 Result80010 00 11 22 33 Accept80010 00 11 22 33 Reject80010 00 BB 22 33 Reject80010 AA BB 22 33 Reject80010 AA BB 22 DD Accept80010 AA BB 22 DD Reject

32 CONTENTS


Example: Data prescaling applied to ID 80010 with mask 9 (considering only changes to the 1st or 4thdata byte). D0-D3 is a 4-byte payload (with D0 the first data byte).

ID (DEC) D0 D1 D2 D3 Result80010 00 11 22 33 Accept80010 00 11 22 33 Reject80010 00 BB 22 33 Reject80010 AA BB 22 33 Accept80010 AA BB 22 DD Accept80010 AA BB 22 DD Reject

0.4.5.4 Transmit

This page documents the transmit configuration.



Transmit messages can.transmit

List of CAN bus messages transmitted by the device. Requires a CAN-bus physical mode supportingtransmissions.

Type Max itemsarray 64

Item can.transmit.item

Name can.transmit.item.name

Optional transmit message name.


State can.transmit.item.state

Disabled transmit messages are ignored.


ID Format can.transmit.item.id_format

ID format of the transmit message.


Frame format can.transmit.item.frame_format

Frame format of the transmit message.

Type Default Optionsinteger 0 Standard: 0 Standard RTR: 2 FD: 1



Bit-Rate Switch can.transmit.item.brs

Determines if an FD message is transmitted using a switched bit-rate.

Type Defaultinteger 0

Include in log can.transmit.item.log

Determines if the transmitted message is included in the log file.


Period (10 ms steps) can.transmit.item.period

Time period of the message transmission. 0: single shot, >0: periodic. Unit is ms.

Type Minimum Maximum Multiple ofinteger 0 4294967290 10

Delay (10 ms steps) can.transmit.item.delay

Offset message within the period or delay a single shot message. If multiple messages are transmitted bythe device, it is recommended to offset each separately to reduce peak load on bus. If period > 0, delay <period. If single-shot, delay can be up to max value. Unit is ms.

Type Minimum Maximum Multiple ofinteger 0 4294967290 10

Message ID (hex) can.transmit.item.id

ID of message to transmit in hex. Example: 1FF.

Typestring

Messages Data (hex) can.transmit.item.data

Data bytes of message to transmit. RTR frames only use the number of bytes do determine the DLC.Example: 01020304 or 0102030405060708.




Period and delay

If multiple transmit messages are defined, it is recommended to spread them in time by using delay. Itmay not be possible to transmit all messages if they are to be transmitted simultaneously.

34 CONTENTS


0.4.5.5 Heartbeat

This page documents the heartbeat configuration



State can.heartbeat.state

Enable to periodically transmit heartbeat signal.


ID Format can.heartbeat.id_format

ID format of heartbeat message.


ID (hex) can.heartbeat.id

ID of heartbeat message in hex. Example: 1FF.

Type Defaultstring 00435353



Note: The heartbeat cannot be disabled using the control signal

Note: The heartbeat feature requires a CAN-bus physical mode supporting transmissions

Payload format

The device can transmit a 1-second periodic heartbeat signal. The signal payload contains logging state(enabled/disabled), the device time and space left on the memory card in MB.

The interpretation of the 8-byte data payload of the heartbeat signal is given below:

Byte No. 0 1 2-5 6-7Interpretation Fixed 0xAA State Epoch time Space left

• Byte 0 has the reserved value 0xAA

• The Epoch time is time-zone and offset adjusted

• Multi-byte fields should be interpreted MSB (Most-SignificantByte) first

• The State holds information on the current rx_state / tx_state:



– 0: RX disabled, TX disabled

– 1: RX enabled, TX disabled

– 2: RX disabled, TX enabled

– 3: RX enabled, TX enabled

Heartbeat with payload: AA 03 5D 78 FB 8B 1D 93

Byte No. 0 1 2-5 6-7Interpretation Fixed State Epoch time Space leftPayload 0xAA 0x03 0x5D78FB8B 0x1D93

• Fixed: 0xAA

• State: RX and TX enabled

• Epoch time: 5D78FB8B16 = 156820980310 -> 11/09/2019 13:50:03

• Space left: 1D9316 = 757110 MB

Heartbeat with payload: AA 00 5D 78 FB 8B 00 00

Byte No. 0 1 2-5 6-7Interpretation Fixed State Epoch time Space leftPayload 0xAA 0x00 0x5D78FB8B 0x0000

• Fixed: 0xAA

• State: RX and TX disabled

• Epoch time: 5D78FB8B16 = 156820980310 -> 11/09/2019 13:50:03

• Space left: 000016 = 010 MB

0.4.5.6 Control

This page documents the control configuration



Control can.control

Control signal

Control reception (rx) state can.control.control_rx_state

Control CAN-bus reception state (including logging)


Control transmission (tx) state can.control.control_tx_state

Control CAN-bus transmission state (including logging)


Start signal can.control.start

36 CONTENTS


ID Format can.control.start.id_format

ID format of the control message.


Message ID (hex) can.control.start.id

ID of the control message in hex. Example: 00435354.


Message ID mask (hex) can.control.start.id_mask

ID mask of the control message in hex. Example: 1FFFFFFF.

Type Defaultstring 1FFFFFFF

Data mask (hex) can.control.start.data_mask

Data trigger mask (byte 0 to the left). Shall match the length of the control signal message.

Type Default Max lengthstring FFFFFFFFFFFFFFFF 16

Data trigger high (hex) can.control.start.data_high

Data trigger high range (byte 0 to the left)


Data trigger low (hex) can.control.start.data_low

Data trigger low range (byte 0 to the left)


Stop signal can.control.stop

ID Format can.control.stop.id_format

ID format of the control message.


Message ID (hex) can.control.stop.id

ID of the control message in hex. Example: 00435354.


Message ID mask (hex) can.control.stop.id_mask



ID mask of the control message in hex. Example: 1FFFFFFF.

Type Defaultstring 1FFFFFFF

Data mask (hex) can.control.stop.data_mask

Data trigger mask (byte 0 to the left). Shall match the length of the control signal message.

Type Default Max lengthstring FFFFFFFFFFFFFFFF 16

Data trigger high (hex) can.control.stop.data_high

Data trigger high range (byte 0 to the left)


Data trigger low (hex) can.control.stop.data_low

Data trigger low range (byte 0 to the left)




The control signal has a flexible configuration allowing for integration with many protocols. The controlsignal can be set to control the device message reception (effectively the logging) and / or the transmission(effectively the processing of the transmit list). The control signal can e.g. be used to start / stop loggingbased on some application parameters, such as speed, RPM or discrete events.

Control signal overview:

• A control signal can be setup for each CAN-bus channel

• One message ID is used for start and one for stop. These can be different or the same

• The message ID can be masked to trigger on a partial ID match (this allows for e.g. J1939 messageswith unknown source)

• The data trigger can be masked to support CAN-bus frames with multiple signals

• The date trigger uses a high/low range, such that any value in the range will trigger (this allowsfor e.g. stop logging when speed is in range 0-10 km/h)

• File splitting is not affected by the control signal (i.e. the control signal does not force additionallog file splits)

Note: The control signal can only be used if accepted by the CAN-bus filter

Note: The control signal data byte fields must match in length vs. the message data

38 CONTENTS


Warning: The start/stop ranges shall be mutual exclusive (cannot both occur at the same time)

Examples

Example: Start / stop on OBD speed response message. The OBD CAN-bus is connected to twoCAN-bus channels. Channel 1 is configured to start / stop message reception based on the OBD speedresponse. Channel 2 does not use the control signal feature.

Start trigger:

• High: 03410DFF0000000016 ⇒ 255 km/h

• Low: 03410D0A0000000016 ⇒ 10 km/h

Stop trigger:

• High: 03410D050000000016 ⇒ 5 km/h

• Low: 03410D000000000016 ⇒ 0 km/h

"start": {"id_format": 0,"id": "7E8","id_mask": "7FF","data_mask": "FFFFFFFF00000000","data_high": "03410DFF00000000","data_low": "03410D0A00000000"

},"stop": {

"id_format": 0,"id": "7E8","id_mask": "7FF","data_mask": "FFFFFFFF00000000","data_high": "03410D0500000000","data_low": "03410D0000000000"

}

Below plot illustrates that Channel 1 message reception (and logging) starts when the speed signal goesabove 10 km/h and stops below 5 km/h. Channel 2 is shown for reference (no control signal).



Example: Start / stop on simple discrete value. In this example the start / stop is controlled via a singlebyte.

Start trigger:

• High: 0116 ⇒ on

• Low: 0116 ⇒ on

Stop trigger:

• High: 0016 ⇒ off

• Low: 0016 ⇒ off

"start": {"id_format": 1,"id": "00435354","id_mask": "1FFFFFFF","data_mask": "FF","data_high": "01","data_low": "01"

},"stop": {

"id_format": 1,"id": "00435354","id_mask": "1FFFFFFF","data_mask": "FF","data_high": "00","data_low": "00"

}

Example: Start / stop on J1939 broadcast speed. This can be used to start logging when a vehicle ismoving.

Start trigger:

• High: 000007000000000016 ⇒ 7 km/h

• Low: 000003000000000016 ⇒ 3 km/h

Stop trigger:

• High: 000001000000000016 ⇒ 1 km/h

40 CONTENTS


• Low: 000000000000000016 ⇒ 0 km/h

"control": {"start": {"id_format": 1,"id": "CFEF100","id_mask": "3FFFF00","data_mask": "0000FF0000000000","data_high": "0000070000000000","data_low": "0000030000000000"

},"stop": {"id_format": 1,"id": "CFEF100","id_mask": "3FFFF00","data_mask": "0000FF0000000000","data_high": "0000010000000000","data_low": "0000000000000000"

}}

0.4.5.7 CAN Errors

The CANedge can detect and log errors on the CAN-bus if enabled in Logging configuration. Thedetected errors are categorized as follows:

• Bit-stuffing error

• Form error

• CRC error

• Bit error

• Acknowledge error

In general, once a node on the CAN-bus has detected an error, it will raise an error frame internally.Depending on the configuration and state of the node, this error frame may also be visible on theCAN-bus. The node can be in one of three states:

1. Active



2. Passive

3. Off

The transitions between the states depends on the number of detected errors in a sliding window. Inthe active state, the node is allowed to emit error frames onto the CAN-bus, while any detected errorframes are kept internal in the passive state. In the off state the node is no longer receiving from ortransmitting to the CAN-bus.

Note: The CANedge will return to the active state in case it ends in the off state.

With reference to the mode field, the following table of behavior is constructed for the CANedge:

Mode Normal Restricted MonitoringState Active Passive Active Passive Active PassiveReceive X X XTransmit XAcknowledge X XInternal error frames X X X X X XExternal error frames X

The CANedge will log all errors it detects if error logging is enabled.

Note: The CANedge is not able to capture any additional CAN information once an error conditionhas been detected. As such, all logged error frames have no information about the associated CAN frameID/flags/payload.

Bit-stuffing Errors

Under normal operation, no more than 5 consecutive bits of a frame may have the same value. If required,the sending node will insert additional stuffing bits to avoid this scenario. If the node detects a violationof this, a bit-stuffing error is raised.

All error frames emitted onto the CAN-bus are violations of the bit-stuffing rules. Thus, the true errorneed not be a bit-stuffing error, but since another node has detected an error, it will signal this to therest of the bus by making the frame invalid.

Depending on whether the CANedge has detected the same error as the other node or not, a moreinformative error message may be logged. See example under acknowledge errors.

Form Errors

Form errors denote that the node has detected a missing or an invalid value in a fixed part of the CANframe.

CRC Errors

If the node has calculated a different value for the cyclic redundancy check than the one embedded inthe frame on the CAN-bus, a CRC error will be raised.

42 CONTENTS


Bit Errors

When a node is transmitting a frame onto the CAN-bus, it can simultaneously sense what the actualvalue on the bus is. If the value differs from the expected value, a bit error is raised.

Acknowledge Errors

When the CANedge has transmitted a frame onto the CAN-bus, it expects another node on the bus toacknowledge the reception by filling a part of the frame. If no acknowledge is detected, the device raisesan acknowledge error.

Example: If a node transmits a frame onto the bus and no other node acknowledges this via the ACKsegment of the frame, that node will detect a missing acknowledge error. As a response, it will emit anerror frame onto the bus, which causes the other nodes to detect a bit-stuffing error.

If the transmitting node had a transmission error counter of 0 before the transmission attempt, 16error frames can be logged in rapid succession, as the node attempts to re-transmit the frame. After16 attempts, the internal error counter of the transmitting node has reached 8 * 16 = 128, and thenode enters the passive error state. The transmitting node is still detecting an error, as no other nodeacknowledges the transmitted frames, but it is no longer allowed to transmit active/dominant error bits.

As the original frame no longer is being destroyed by an error frame from the sender, the other nodeson the bus will now log the intended message, even though it is in an erroneous state due to the lack ofacknowledgement.

0.4.6 LIN

The configuration of LIN Channel 1 and LIN Channel 2 is identical.

The LIN configuration is split into the following sections:

0.4.6.1 Physical

This page documents the physical configuration



Mode lin.phy.properties.mode

Device LIN bus mode.

Type Default Optionsinteger 0 Subscriber: 0 Publisher: 1

Bit-rate lin.phy.properties.bit_rate

Type Default Optionsinteger 19200 2400: 2400 9600: 9600 10400: 10400 19200: 19200





0.4.6.2 Frame Table

This page documents the frame table configuration



Name lin.frames.items.name

Optional frame name.


Frame ID (hex) lin.frames.items.id

ID of frame in hex. Example: 0F.


Frame Length (decimal) lin.frames.items.length

Length of the frame in decimal.

Type Minimum Maximuminteger 1 8

Checksum Type lin.frames.items.checksum_type

Type of the checksum used on the LIN frame.

Type Default Optionsinteger 0 Enhanced: 0 Classic: 1



The LIN controller expects default data lengths and checksums as explained in LIN . LIN-frames usinga different configuration (length, checksum or both) can be explicitly configured using the frame table.

Note: LIN frames satisfying the default expected configuration do not need to be inserted in the frametable.

0.4.6.3 Transmit

This page documents the transmit configuration

44 CONTENTS




Name lin.transmit.items.name

Optional transmit rule name.


State lin.transmit.items.state

Disabled transmit rules are ignored.


Frame ID (hex) lin.transmit.items.id


Data (hex) lin.transmit.items.data




The interpretation of the transmit list depends on the configuration of LIN bus mode:

Publisher mode

The number of bytes entered in the data field determines the interpretation of the transmission frame:

Length of data is zero

The transmit is a SUBSCRIBE frame, meaning that a Subscriber on the bus is expected to provide thedata payload (satisfying the frame table).

Length of data is above zero

The transmit is a PUBLISH frame, meaning that the CANedge provides the data payload.

In Publisher mode, the CANedge schedules the frame transmissions configured by the period and delay.

Warning: Be aware that transmit uses period and delay to schedule transmissions. This is adifferent concept than what is used by LDF files.



Subscriber mode

In Subscriber mode, the CANedge awaits a SUBSCRIBE frame with a matching ID from the busPublisher node. The number of bytes provided shall satisfy the frame table.

Warning: If the transmit list contains multiple frames using the same ID, then only the first entryis used.

0.4.6.4 Topology

A LIN-bus consists of a Publisher node and one or more Subscriber nodes. The Publisher controlsscheduling of messages on the LIN-bus, and the Subscriber nodes react to the emitted messages.

A message on the LIN-bus can either be a PUBLISH message, in which case Publisher node transmitsboth the message ID and data, or a SUBSCRIBE message, where the Publisher node only emits themessage ID and one of the Subscriber nodes fill the data section of the message.

The configuration of the LIN network shall ensure that each message has one producer, such that eachPUBLISH message is filled with data by the Publisher, while each SUBSCRIBE message has a nodeconnected to the network which can provide the data for the message.

An example of the bus topology with the CANedge connected as a subscriber is illustrated below:

The CANedge is primarily intended to act as a Subscriber on the LIN-bus. In lieu of a Publisher node,the CANedge can be configured to emulate a simple Publisher node. In this case, the scheduling ofmessages on the network has to be done through the transmit configuration for the interface. Since onlystatic data can be entered in the configuration, the simple Publisher node emulation cannot performdynamic operations based on the LIN-bus activity.

0.4.6.5 Data length

Unless configured otherwise, the device assumes that the length of the LIN frame data payload is alwaysdefined by the message ID (bits 5 and 6 of the identifier), as defined in the table below:

Message ID Data length00-31 (0x00-0x1F) 232-47 (0x20-0x2F) 448-63 (0x30-0x3F) 8

This can be overridden in the configuration of the frame table.

0.4.6.6 Checksum

Supports LIN 1.3 classic checksum and LIN 2.0 enhanced checksum format. By default, all frames exceptID 0x3C and 0x3D will use enhanced checksum. This can be overridden on a frame by frame basis in

46 CONTENTS


the configuration of the frame table.

0.4.6.7 LIN Errors

The CANedge can detect and log errors on the LIN-bus if enabled in Logging configuration. The detectederrors are categorized as follows:

• Checksum errors

• Receive errors

• Synchronization errors

• Transmission errors

The amount of associated data depends on the type of error. E.g. synchronization errors cannot con-tain information about the message ID, as it happens before that field is transmitted, and checksuminformation is not embedded in other cases than the checksum error case.

Checksum Errors

Checksum errors denotes that the node has calculated a different checksum than the one embedded inthe LIN message on the bus. This can be an indicator of wrong configuration for the frame ID in theCANedge frame table.

Example: In case no information is known about the LIN bus in advance, the default frame table canbe used with error logging enabled to help reverse engineer the actual frame table. Any message IDsdeviating from the standard table (and present on the LIN-bus) will get a logged entry. These IDs canthen be reconfigured in the CANedge frame table, in an attempt to find the correct settings.

Note that it can be necessary to change both message length and checksum model in order to get a validconfiguration.

Receive Errors

Receive errors are logged when a fixed part of the LIN message is not as expected, or that the nodedetects a mismatch between the value being transmitted and the value sensed on the LIN-bus.

Synchronization Errors

Synchronization errors indicates an invalid synchronization field in the start of the LIN message, or thatthere is a too large deviation between the configured bitrate for the node and the detected bitrate fromthe synchronization field.

Transmission Errors

Transmission errors can only occur for IDs registered as SUBSCRIBER messages. If there is no node onthe LIN-bus responding to a SUBSCRIBER message, a transmission error is logged.

0.4.7 Connect

This page documents the Connect configuration.

The Connection configuration is split into the following sections:



0.4.7.1 WiFi

This page documents the wifi configuration



Mode connect.wifi.mode

The WiFi mode.

Type Default Optionsinteger 0 Station mode: 0

Key format connect.wifi.keyformat

The format of the key used for all entries in the access point list. Can be used to hide the WiFi passwordsstored on the device.

Type Default Optionsinteger 0 Plain: 0 Encrypted: 1

Access points connect.wifi.accesspoint

List of access points. Connects to the first available AP in list.

Type Max itemsarray 5

Item connect.wifi.accesspoint.item

SSID connect.wifi.accesspoint.item.ssid

Access point SSID (name of access point)


Password connect.wifi.accesspoint.item.pwd

Type Default Max lengthstring 64

Minimum RSSI (received signal strength indicator), 0-100% connect.wifi.accesspoint.item.minrssi

Sets a minimum required access point signal strength. The device will not connect to the access point ifthe measured signal strength is below the value of this field.

Type Default Minimum Maximuminteger 0 0 100



48 CONTENTS


Multiple WiFi access points

The device supports multiple access points. The device will attempt to connect to the access points inthe prioritized order in which they are entered in the configuration file. If unable to connect to an accesspoint or if the signal strength is below the minimum RSSI%, the device will attempt the next one fromthe list. Every time the device initiates a new WiFi connection, it will cycle through the list in thismanner, starting from the top.

Using an RSSI% of 0 (default) means that the device will attempt to connect to the AP, even if thesignal strength is practically non-existent.

0.4.7.2 S3 server

This page documents the s3 server configuration

Note: If a HTTPS (TLS) server Endpoint is used, refer to the Security Section for more informationon how to setup certificates.





Request-style

S3 supports two different request styles path and virtual hosted. The device supports both styles.

With the virtual hosted style, the subdomain is specific to the bucket, which makes it possible to useDNS to map a specific bucket to an IP address.

Warning: Some S3 servers may only support one of the two request formats.

Path-style http header example:

GET /[BUCKET_NAME]/[OBJECT_NAME] HTTP/1.1Host: [DOMAIN]...

Virtual hosted-style http header example:

GET /[OBJECT_NAME] HTTP/1.1Host: [BUCKET_NAME].[DOMAIN]...



0.5 Device file

A Device File (device.json) is located in the root of the SD card with info on the device. The contentof the Device File is updated when the device powers on.

{"id": "4F07A3C3","type": "0000001F","kpub": "l27UKi4ehjpxxEdmRstBk5UaqSGQYnfylzUNs9EOoJfDodvr/

→˓PqNnMrz61IxzrBfFTmuhw2K2cJ4q60iFiYM8w==","fw_ver": "01.01.02","hw_ver": "00.01","cfg_ver": "01.01","cfg_name": "config-01.01.json","cfg_crc32": "9ECC0C10","sch_name": "schema-01.01.json","log_meta": "Truck1","space_used_mb": "36/7572","sd_info": "000353445341303847801349A26A0153","sd_used_lifespan": "2","wifi_fw_ver": "19.3.0/19.6.1","wifi_mac": "F8-F0-05-94-39-2E","certs_server": ["5BDA1A96DF69FEB62E2E0A61BD2672C03CAA9473",

→˓"F46B682C4D72E3394C22189AE16DD9A79AFFFD82"]}

Additional content may be added to the device.json in future firmware updates.

Fields explained

• id: Device unique ID number

• type: Device type (CANedge1 = 0000001D, CANedge2 = 0000001F)

• kpub: Device public key in Base-64 format

• fw_ver: Firmware version

• hw_ver: Hardware version

• cfg_ver: Configuration File version

• cfg_name: Configuration File name

• cfg_crc32: Configuration File checksum

• sch_name: Configuration Rule Schema name

• log_meta: Configurable device string (e.g. application name)

• space_used_mb: The SD-card used space of the total in MB ([used]/[total])

• sd_info: Information about the SD card, including unique serial number in hex

• sd_used_lifespan: The SD-card self-reported health in percent of lifetime used, or ? if unavailable

• wifi_fw_ver: WiFi module version

• wifi_mac: WiFi module MAC address

• certs_server: List of loaded TLS certificate hashes from the Server Certificate Bundle

50 CONTENTS


0.6 Log file

This page documents the log files stored on the device SD-card.

0.6.1 Organization

Log files are organized by the following path structure:

LOG/[DEVICE_ID]/[SESSION_NUMBER]/[SPLIT_NUMBER].[FILE_EXTENSION]

The path is constructed from the following parts:

• LOG: Static directory name used to store log files

• DEVICE_ID: Globally unique device ID

• SESSION_NUMBER: Increased by one for each power cycle1

• SPLIT_NUMBER: Reset to 1 on each power cycle and increased by one for each file split

• FILE_EXTENSION: The file extension selected in the configuration (MF4|MFC|MFE|MFM)

For details on log file splits and related limits, see the Logging Configuration section.

File extension

The default extension is MF4. With compression/encryption enabled the extension changes:

Compression enabled Encryption enabled File extension.MF4

X .MFCX .MFE

X X .MFM

With both compression and encryption enabled, the data is first compressed, then encrypted.

For details on compression and encryption, see the Logging Configuration section.

Path example

Example: Log file path: LOG/3B912722/00000004/00000189.MF4

• LOG: The static directory common for all log files

• 3B912722: The unique ID of the device which generated the log file

• 00000004: Generated during the 4th session / power cycle

• 00000189: Is log file number 189 of the session

• MF4: File type

0.6.2 MDF

The CANedge logs data in the industry standard MDF4 format, standardized by ASAM. MDF4 is abinary format which allows compact storage of huge amounts of measurement data. It is specificallydesigned for bus frame logging across e.g. CAN-bus, LIN-bus and Ethernet. MDF4 is widely adoptedby the industry and supported by many existing tools.

Specifically, the CANedge uses MDF version 4.11 (file extension: *.MF4).1 The session number is also increased by one if the number of splits in one session exceeds 256

0.6. Log file 51


Timestamps

Each record is timestamped with 50 us resolution2.

Finalization & sorting

The CANedge stores log files as unfinalized and unsorted to enable power safety. Finalization3 andsorting4 can be done as a post-processing step to speed up work with the files.

Note: It may be necessary to finalize/sort a log file before it is loaded into some MDF tools

Additional metadata about the device is captured in the files, including many of the fields exposed inthe device file.

• serial number: Device unique ID number

• device type: Device type (CANedge1 = 0000001D, CANedge2 = 0000001F)

• firmware version: Firmware version

• hardware version: Hardware version

• config crc32 checksum: Configuration File checksum

• storage total: The SD-card total space in MB

• storage free: The SD-card free space in MB

• storage id: The SD-card identifier

• session: File session number

• split: File split number

• comment: Configurable device string (e.g. application name)

0.6.2.1 CAN Formats

Data from the CAN bus are stored in three distinct channels in the MDF log files:

• Data in CAN_DataFrame

• Remote requests in CAN_RemoteFrame

• Errors in CAN_ErrorFrame

Some fields are common among all the channels while others are unique to a specific channel, as visualizedby the table below.

2 Changes to the system time (RTC) caused by the WiFi RTC auto sync take effect on the next file split, or after apower-cycle.

3 The MDF file header includes information on how to finalize the MDF file before use4 Sorting refers to an organization of the log records which enable fast indexing. It is not related to sorting of timestamps.

52 CONTENTS


Table 1: Fields for CAN channelsField name Field description CAN_DataFrame CAN_RemoteFrame CAN_ErrorFrameTimestamp Relative timestamp X X XID CAN ID X XIDE Extended ID flag X XBusChannel Hardware channel X X XDir Direction (RX/TX) X XDLC DLC code X XDataLength Translated DLC code X XBRS FD Bitrate switch XEDL FD flag XESI FD ESI flag XDataBytes Data XErrorType Error type X

For all messages in CAN_RemoteFrame, it is implied that the RTR flag is set.

If enabled, detected errors on the CAN bus can be logged alongside the other entries. These are devoidof data, and only contain an error code denoting the type of error detected:

0. Unknown error

1. Bit error

2. Form error

3. Bit-stuffing error

4. CRC error

5. Missing acknowledge for a message sent by the device

For more information on CAN-bus errors, see CAN configuration.

0.6.2.2 LIN Formats

Data from the LIN bus are stored in five distinct channels in the MDF log files:

• Checksum errors in LIN_ChecksumError

• Data in LIN_Frame

• Receive errors in LIN_ReceiveError

• Synchronization errors in LIN_SynchronizationError

• Transmission errors in LIN_TransmissionError

Some fields are common among all the channels while others are unique to a specific channel, as visualizedby the table below. It is possible, though unlikely, for the same LIN frame to trigger multiple errors.

0.6. Log file 53


Table 2: Fields for LIN channelsField name Field descrip-

tionLIN_ChecksumErrorLIN_FrameLIN_ReceiveErrorLIN_SynchronizationErrorLIN_TransmissionError

Timestamp Relativetimestamp

X X X X X

ID ID X X X XBusChannel Hardware

channelX X X X X

Dir Direction(RX/TX)

X X

DataBytes Data X XDataLength Number of

data bytesX X

Received-DataByte-Count

Number ofdata bytes

X X

Checksum Receivedchecksum

X

Checksum-Model

Classi-cal/Enhanced

X

For checksum errors, the logged checksum is the one received on the LIN bus. The non-matchingcalculated checksum can be derived from the logged data and checksum model.

For more information on LIN-bus errors, see LIN configuration.

0.6.3 Generic header

While plain MDF files are saved as MF4, encryption and/or compression uses a custom header to identifyand store relevant information for the files. All file headers consist of a generic 20 byte header, followedby any specialized fields.

The generic header starts with an identifying sequence of the ASCII code for Generic File5. Followingare information of the versioning scheme as major and minor numbers, file type and file sub-type. Finally,the device ID is stored. All numbers stored in the generic header are unsigned and big endian formatted.

|<- 8 bytes ->|| Byte | Byte | Byte | Byte | Byte | Byte | Byte | Byte || 'G' 'e' 'n' 'e' 'r' 'i' 'c' ' '->||<-'F' 'i' 'l' 'e' | V Ma | V Mi | FT | FTI || Device ID (Uint32, BE) |

If required, a generic file may contain a footer as well, as specified by the format.

0.6.3.1 Encrypted files

Encrypted files will have a file type of 0x11. The device supports AES encryption in Galois CounterMode (GCM), with a file sub-type of 0x01. The current version of the format is 0x00 for both majorand minor. The encrypted file header stores three additional fields:

• The 12 bytes long initialization vector

• The number of hashing iterations for the key, stored as a 32 bit unsigned number in big endianformat

• 16 bytes of salt data for the hashing of the key5 Generic File maps to 12 bytes of ASCII, with no zero termination of the string.

54 CONTENTS


|<- 8 bytes ->|| Byte | Byte | Byte | Byte | Byte | Byte | Byte | Byte || IV/Nonce ->||<- IV/Nonce | Iterations (Uint32, BE) || Salt ->||<- Salt |

The encrypted file contains an additional footer. This stores the 16 byte tag generated when AES runsin GCM mode. When decrypting, this tag should be checked to ensure the validity of the decrypteddata. There is no alignment requirement for the footer.

|<- 8 bytes ->|| Byte | Byte | Byte | Byte | Byte | Byte | Byte | Byte || GCM Tag ->||<- GCM Tag |

0.6.3.2 Compressed files

Compressed file will have a file type of 0x22. At present, the only supported compression format isheatshrink based. This is denoted by a file sub-type of 0x01. The current version of the format is 0x00for both major and minor. The additional header data are two unsigned 32 bit numbers: Lookaheadand window sizes.

|<- 8 bytes ->|| Byte | Byte | Byte | Byte | Byte | Byte | Byte | Byte || Lookahead (Uint32, BE) | Window (Uint32, BE) |

Following the header is the compressed data stream. There is no footer.

0.6.3.3 Encrypted and compressed files

If the file is both encrypted and compressed, it has been processed in two steps/streams. First the datais piped through a compression step, next it is piped through an encryption step.

Various software/API tools for the CANedge enable easy decryption/decompression of log files.

0.6. Log file 55


0.7 Remote access

0.7.1 Network

The CANedge supports wireless connectivity over WiFi. The WiFi specifications are given here.

0.7.1.1 WiFi

The CANedge is able to connect to a WiFi access point (AP).

The CANedge expects to be assigned an IP by a DHCP service running on the access point. The networkapplication name (host name) of a connected CANedge is the unique device ID.

0.7.1.2 Network topology

The following describes local and remote server network topologies.

Warning: Make sure that firewalls allow S3 (e.g. port 9000) and NTP (port 123) traffic.

Local network topology

A local network topology is illustrated below. With the local topology, the device does not requireinternet access as the server is located in the same local network1.

Remote network topology

A remote network topology is illustrated below. With the remote topology, the device and server arelocated at two separate networks. Internet connection is used to connect the two local networks andallow the device to connect to the server.

0.7.2 Server

1 Make sure to use a local NTP server if RTC auto sync is enabled

56 CONTENTS


Table of Contents

• Server

– Server types

∗ Local

∗ Dedicated

∗ Cloud

– Transfer throughput

0.7.2.1 Server types

In the below we briefly outline the main server types.

Local

An S3 compatible server can easily be installed on any regular office PC.

In the simplest case, the server is run on the PC that is also used for analysing data. In this case, theinstallation is as simple as running any other PC program.

Typical use cases:

• Devices connect to the server over a local network (LAN)

• One to a few devices

• A simple setup is preferred

Dedicated

Like with the local server setup, the S3 compatible server can be installed on a dedicated server.

Typical use cases:

• Devices connect to the server over an external network (WAN)

• It is preferred to store data on a company controlled server

• Users wish to avoid signing cloud service subscription plans

Cloud

The S3 can be run in the cloud with Amazon (AWS) or any other S3 compatible provider.

Typical use cases:

• It is preferred to outsource server hosting

• Users wish to combine data storage with other services (e.g. cloud computing)

0.7.2.2 Transfer throughput

The device-to-server throughput1 is highly dependent on the device-to-server latency23.1 The total quantity of data transferred within a unit of time2 Time needed for a single packet transfer3 This is particularly the case due to the limited resources of the device

0.7. Remote access 57


If multiple servers are available (such as regional cloud server endpoints), make sure to select a serverwith low device-to-server latency.

0.7.3 Managing devices

This section covers how the CANedge interfaces to an S3 server and how to manage devices.

0.7.3.1 Buckets

Each CANedge device is associated with a specific S3 bucket name. The device will (depending on theconfiguration) e.g. push files and look for configuration updates within that specific bucket.

Note: The device is not able to create a bucket. Buckets must be created on the server before thedevice is connected

0.7.3.2 Device ID

Each CANedge device carries a globally unique 4-byte device ID (e.g. A1B2C3D4). The device ID is usedin the communication with S3 so that multiple devices connected to the same bucket do not conflict.The root path of a given device is given by the Bucket name and the unique ID:

[BUCKET_NAME]/[DEVICE_ID]

0.7.3.3 Log files

The device uploads closed log files to the S3 server. When a log file has been successfully uploaded, it isdeleted on the SD-card. Log files pushed to the server are named according to the following pattern:

[BUCKET_NAME]/[DEVICE_ID]/[SESSION_NUMBER]/[SPLIT_NUMBER]-[EPOCH_TIME].[EXT]

• EPOCH_TIME: Epoch upload time in HEX (e.g. 2020/01/01 00:00:00 becomes 5E0BE100)

• EXT: one of the possible file extensions supported by the device.

Note: Upload of many small log files has a higher network overhead and will result in lower throughput.Select a higher log file split_size (refer the Logging Configuration Section) for better throughput if thenetwork stability allows it. For reliable networks, aim for at least 10 MB files.

Note: If the server-to-device confirmation that a log file has been uploaded successfully is lost (e.g.due to network problems), the device will upload the log file again. This can result in multiple identicallog files with different EPOCH_TIME timestamps. Copies of the same log file (same SESSION_NUMBER andSPLIT_NUMBER) should be ignored or removed.

Note: If log file time splitting is used (rather than file size based splitting), consider to use thesplit_time_offset to avoid that all devices upload new log files to the server at the same time. Formore information, refer the Logging Configuration Section.

58 CONTENTS


Meta data

S3 allows additional meta data to be attached to each file. The device adds below S3 meta data:

• X-Amz-Meta-Hw: The device hardware revision

• X-Amz-Meta-Fw: The device firmware revision

• X-Amz-Meta-Ssid: The WiFi SSID which was used to upload the file/object

• X-Amz-Meta-Timestamp: The last-modified local time timestamp of the file/object in formatYYYYMMDDTHHMMSS

• X-Amz-Meta-Put-Index: S3 PUT operation counter

0.7.3.4 Heartbeat (Device File)

The device can be configured to periodically push a Heartbeat object (Device File) to the server:

[BUCKET_NAME]/[DEVICE_ID]/device.json

0.7.3.5 Configuration Over-The-Air (COTA)

The device configuration can be managed directly from the S3 server. Both the Rule Schema and theConfiguration File are synchronised with the S3 Server if OTA (over-the-air) is enabled.

Rule Schema

The Rule Schema is automatically uploaded once for each power cycle. This ensures that the server alwaysknows the configuration rules of a specific device. If the firmware is updated, the device automaticallyuploads the Rule Schema matching the new firmware.

The Rule Schema is placed in the device root path and named as below:

[BUCKET_NAME]/[DEVICE_ID]/schema-01.02.json

Configuration File

The device periodically checks the S3 Bucket for updates to the Configuration File. If the ConfiguratonFile is updated on the server it is automatically downloaded and applied by the device (causing a powercycle). If no Configuration File is located on the server it is automatically uploaded by the device.

The Configuration File is placed in the device root path and named as below:

[BUCKET_NAME]/[DEVICE_ID]/config-01.02.json

Warning: Configuration changes made via the SD card will be overwritten if a Configuration Fileis on the server. To apply local changes, first remove the server Configuration File

0.7.3.6 Firmware Over-The-Air (FOTA)

The device periodically checks the S3 bucket for firmware updates if OTA (over-the-air) is enabled.

Updating firmware over-the-air works similarly to updating firmware via the SD card. The FirmwareFile is placed in the device S3 root path and named firmware.bin:

[BUCKET_NAME]/[DEVICE_ID]/firmware.bin

If a valid Firmware File is added to this path, the device downloads and stores it on the SD. If the newfirmware is a MAJOR or MINOR upgrade, an updated Configuration File must also be provided.



FOTA sequence with same MAJOR/MINOR version (example: 01.02.03 to 01.02.04)

1. The firmware.bin Firmware File is placed in [BUCKET NAME]/[DEVICE ID]/firmware.bin

2. The device downloads the Firmware File and reboots

3. The device continues to use the same Configuration File

FOTA sequence with new MAJOR/MINOR version (example: 01.02.03 to 01.03.00)

1. The new Configuration File config-01.03.json is placed in [BUCKET NAME]/[DEVICE_ID]/config-01.03.json

2. The firmware.bin Firmware File is placed in [BUCKET NAME]/[DEVICE_ID]/firmware.bin

3. The device downloads the Firmware and Configuration Files and reboots

4. The device uses the updated Configuration File

Note: Upgrading to a new MAJOR or MINOR version requires an updated and compatible Configu-ration File. If this is not found, the update is aborted

0.7.3.7 Server certificates over-the-air

The device periodically checks S3 for server certificate updates if OTA (over-the-air) is enabled.

Updating server certificates over-the-air works similarly to Local installation of certificate(s). The ServerCertificate Bundle is placed in the S3 device root path and named certs_server.p7b:

[BUCKET_NAME]/[DEVICE_ID]/certs_server.p7b

If a valid Server Certificate Bundle file is added to this path, the device downloads and stores it on theSD and reboots. Refer to Prepare certificate(s) on how to prepare a Server Certificate Bundle.

Warning: When updating the Server Certificate Bundle over-the-air, special care must be taken toensure that the device can access a server both before and after the update. It is recommended toalways include both the current and new certificates in the bundle while any transition is performed.

Below provides recommended Server Certificate Bundle update sequences. Refer to Device file for infor-mation on how to verify loaded certificates (used in the sequences below).

Upgrade a server connection from HTTP to HTTPS (TLS)

1. Generate a Server Certificate Bundle (certs_server.p7b) with the certificate(s)

2. Upload the Server Certificate Bundle to the S3 server

3. Wait for the device file to show that the certificate has been loaded

4. Update the configuration file to enable HTTPS

Replace a soon-to-expire-certificate

1. Generate a Server Certificate Bundle (certs_server.p7b) with both certificate(s) (the soon-to-expire and the new).

2. Upload the Server Certificate Bundle to the S3 server

3. Wait for the device file to show that both certificates have been loaded

60 CONTENTS


4. Generate a new Server Certificate Bundle without the soon-to-expire certificate and repeat step 2and 3.

Warning: Above sequence assumes that both certificates are valid during the process.

Change to another S3 endpoint

1. Generate a Server Certificate Bundle (certs_server.p7b) with the current and new certificate(s)

2. Upload the Server Certificate Bundle to both the current and new S3 servers

3. Wait for the device file to show that both certificates have been loaded

4. Upload the new configuration file to both the current server with the updated server information(pointen to the new server)

5. Wait for the device to connect to the new server (monitor either if the configuration file or device.json is uploaded)

6. Generate a Server Certificate Bundle (certs_server.p7b) with only the new certificate(s)

7. Upload the Server Certificate Bundle to new S3 server

8. Wait for the device file to show that only the new bundle has been loaded

0.7.4 Security

This page describes how to create a secure connection between the CANedge and the S3 server.

0.7.4.1 Server security modes

The following describes three Server Security Modes. It is recommended to start using the Low SecurityMode and migrate to the Medium Security Mode or High Security Mode before the system goes live.

Medium Security Mode and High Security Mode use HTTPS (Transport Layer Security, TLS v1.2).

Below is an overview of the security modes:

Low Medium HighAPI credentials X X XTransport security (TLS) X XServer identity authentication (TLS) X XDevice identity authentication (TLS) X

Warning: High Security support is pending future firmware update

Low security mode

The security provided by the Low Security Mode is illustrated below:



API credentials

The device uses the server S3 credentials (AccessKey and SecretKey) to calculate an authenticationsignature for each request. Upon reception, the server verifies the signature (see the S3 REST API fordetails). Only devices with a valid AccessKey and SecretKey pair can gain access to the S3 storage.

Warning: The AccessKey and SecretKey pair is shared amongst all nodes in the network

Warning: Data transmissions between the device and server are in plain text

Installation requirements

Devices are pre-configured with the server S3 API credentials (AccessKey and SecretKey).

Medium security mode

The security provided by the Medium Security Mode is illustrated below:

Warning: The device is not authenticated by the server

API credentials

Same as Low Security Mode

Transport security

HTTPS (TLS) is used to encrypt data between the device and the server. The device supports a limitedset of ciphers for communicating with the remote server.

62 CONTENTS


Server identity authentication

HTTPS (TLS) is used to authenticate the server certificate. This ensures that devices only allow con-nections to trusted servers.

Server certificate authentication sequence:

Installation requirements

Same as Low Security Mode. Additionally, devices are pre-loaded with the CA certificate used to issuethe server certificate - see the installation details further below.

High security mode

For details on this mode, see the online documentation.

0.7.4.2 TLS/HTTPS

The CANedge uses TLS v1.2 for secure communication12, providing the following mechanisms:

• Encryption of data transmissions

• Server identity authentication (using certificates)

• Device identity authentication (using certificates)

The CANedge supports the following ciphers for handshaking and encrypting the communication withthe remote server:

1 The device is not compatible with servers that only support DSA certificates.2 512, 1024, 2048 bit key sizers are supported. 2048 bit key size is recommended, see https://knowledge.digicert.com/

generalinformation/INFO1684.html


https://knowledge.digicert.com/generalinformation/INFO1684.html

https://knowledge.digicert.com/generalinformation/INFO1684.html


Cipher Group 1 Group 2 Group 3TLS_RSA_WITH_AES_128_CBC_SHA X X XTLS_DHE_RSA_WITH_AES_128_CBC_SHA X X XTLS_ECDHE_RSA_WITH_AES_128_CBC_SHA X X XTLS_RSA_WITH_AES_128_CBC_SHA256 X XTLS_DHE_RSA_WITH_AES_128_CBC_SHA256 X XTLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 X XTLS_RSA_WITH_AES_128_GCM_SHA256 XTLS_DHE_RSA_WITH_AES_128_GCM_SHA256 XTLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 X

These are divided into 3 groups, with each group containing a larger set of supported ciphers. Connectionswill initially be attempted with only group 1. In case the connection attempt fails, the CANedge willattempt with the next group, until only group 3 will be used for connections.

TLS uses a chain of certificates for establishing trust. At the top of the chain is the root certificateauthority (CA). At the button is the user (application) certificate. In this specific case, the user certificateis used to identify either the server or the client (device).

In order to trust the user certificate, one of the certificates above it in the trust chain must be trusted.

Warning: Be aware that certificates have an expiration date. An expired certificate is not trusted

Enabling server identity authentication

This section explains how to enable TLS/HTTPS server identity authentication on the CANedge.

When server identity authentication is used (Medium Security Mode and High Security Mode), the servermust provide a trusted certificate proving its identity in order for the CANedge to accept the connection.

The server certificate is trusted if the device is configured to trust one of the certificates above it in thetrust chain. Self-signed certificates are used directly, as these do not form a trust chain.

64 CONTENTS


The device supports up to 10 server certificates as a bundled PKCS#7 (.p7b) file3.

Some servers have several certificates installed. The device uses the TLS extension field Server NameIndication (SNI) to indicate to the server which certificate to return (if a hostname is used as endpoint).

Below describes how to first prepare and then install trusted server certificates on the device.

Prepare certificate(s)

Trusted certificates are stored in a single file (/certs_server.p7b) on the device. The flow chart belowshows how to prepare the certificate bundle depending on the number of certificates to install:

Zero certificates (Clear)

Clear all loaded certificates by creating an empty/blank file called certs_server.p7b

One certificate (Rename)

Prepare a single certificate by renaming:

1. Acquire the trusted certificate (e.g. the root certificate) in a supported format (.pem, .cer, .crt,.der)

2. Rename the certificate to certs_server.p7b

3 The device does not support multiple certificates from the same issuer (the Issuer field) as this field is used todistinguish the certificates



Multiple certificates (Bundle)

Prepare multiple certificates by creating a PKCS#7 bundle containing all the certificates.

Generation of certificate bundles requires a tool, such as the free OpenSSL library4

1. Acquire the trusted certificates (e.g. root certificates) in a supported format

2. Copy all the certificates into a single folder

3. Open a console/command prompt in the folder

4. Run openssl crl2pkcs7 -nocrl -certfile certificate_1.pem -certfile certificate_2.pem -out certs_server.p7b with the filenames of the certificates replacing certificate_1,certificate_2 etc. If more than 2 certificates are to be stored, insert additional -certfilecertificate_n clauses5

Local installation of certificate(s)

The certificate bundle can be installed on the device by placing it in the root of the SD-card.

1. Copy the certificate file certs_server.p7b to the root folder of the device SD card

2. Update the device Configuration File to use the https:// endpoint and the correct port

3. Confirm that a hash of the loaded certificate is written to the device.json file on startup

4. Verify that data is uploaded correctly via HTTPS

Warning: Make sure to update the endpoint to use https://

Remote installation of certificate(s)

The certificate bundle can be installed on the device by placing it on S3. For more information refer toServer certificates over-the-air .

Enabling device identity authentication

Warning: Device identity authentication support is pending future firmware update

If device identity authentication is used (High Security Mode), the device must provide a trusted certifi-cate proving its identity in order for the server to accept the connection. The device certificate is trustedif the server is configured to trust one of the certificates above it in the trust chain.

4 Linux: Check the package manager for the distribution, Mac OS: Homebrew, Windows: Available as a part of pre-packaged git

5 The input certificate format must be PEM/base64 encoded DER

66 CONTENTS

https://www.openssl.org/

https://brew.sh/

https://git-scm.com/download/win/


0.8 Firmware

0.8.1 Firmware download

See the online documentation for the latest Firmware Files and changelog.

0.8.1.1 Mandatory update steps

Some upgrade steps are mandatory and cannot be skipped. Skipping mandatory update steps can resultin unexpected behavior. The mandatory update sequence is illustrated below.

01.03.XX –> 01.04.XX

Warning: From 01.04.XX TLS certificates placed as single files in certs_root are no longer sup-ported. Make sure that certificates are migrated to the bundle format prior to performing the updateas explained in Section TLS/HTTPS .

01.02.XX –> 01.03.XX

Warning: From 01.03.XX TLS certificates placed as single files in certs_root are supported butobsolete. It is replaced by loading from a bundle file (for more information refer to TLS/HTTPS).Support for single-files certificates is removed in the next minor or major update. It is recommendedto migrate from single-files certificates to certificate bundle while the device is running firmware01.03.XX

00.07.XX –> 01.02.XX

Warning: Firmware upgrade from 00.07.XX to 01.02.XX includes a one-time boot migration step.The migration step formats the SD-card resulting in loss of existing log files. The configuration andcertificates are copied back to the card after migration

Firmware Files can be downloaded from the online documentation.

This page describes how to upgrade the device firmware.

0.8.2 Firmware versioning & naming

The device firmware versioning is inspired by the semantic versioning system.

Each firmware is assigned three two digit numbers: MAJOR, MINOR, PATCH:

• MAJOR: Incompatible changes (e.g. requires changes to the Configuration File)

• MINOR: New backwards-compatible functionality (e.g. new fields in the Configuration File)

0.8. Firmware 67


• PATCH: Backwards-compatible bug fixes (e.g. no changes to the Configuration File)

The firmware files available for download are zipped with naming as follows:

firmware-[MAJOR].[MINOR].[PATCH].zip

Example:

firmware-01.02.03.zip

0.8.3 Firmware upgrade

The device supports in-the-field firmware upgrades.

Note: The firmware upgrade process is power safe (tolerates power failures). However, it is recom-mended to ensure that the process completes

0.8.3.1 Upgrade process

Upgrading initiates when the device is powered and has been prepared with a new Firmware File:

1. Power is applied to device

2. The green LED comes on

3. If the firmware is valid, the green LED blinks 5 times, else the red LED blinks 5 times

4. The green LED remains solid while the firmware is upgraded (~20 sec)

5. If the upgrade succeeds, the green LED blinks 5 times, else the red LED blinks 5 times

6. The upgraded firmware is started

Note: The green LED comes on later than usual when a firmware upgrade is initiated

Note: The device automatically removes any Firmware Files (firmware.bin or firmware_wifi.bin)when the upgrade has completed. Firmware Files should never be manually deleted during the upgradeprocess.

Note: The CANedge2 upgrades the WiFi related features as a second step of the firmware upgradeprocess after the main firmware has started. Allow the CANedge2 a few minutes to complete the secondstep of the firmware upgrade. If power is lost during the second step, the device will resume next timeit powers on.

0.8.3.2 Configuration update

If a device is updated to a firmware version with a different MAJOR or MINOR number, then the Configu-ration File also needs updating (i.e. with an updated name and structure matching the new firmware).The Configuration File is named as described in the Configuration section. A default Configuration Fileand corresponding Rule Schema are contained in the firmware download zip.

To modify an existing Configuration File, it can be useful to load the new Rule Schema in an edi-tor together with the old Configuration File. After making the necessary updates, save the modifiedConfiguration File with a name matching the new version.

68 CONTENTS


Note: The firmware can be upgraded without providing a new compatible Configuration File. In thiscase, the device will create a default Configuration File on the SD card

0.8.3.3 Upgrade from SD card

The firmware can be upgraded by placing a Firmware File on the SD and powering the device:

1. Download the firmware zip (Firmware File + Configuration File + Rule Schema)

2. Place the firmware.bin file on the SD card (root directory)

3. If MAJOR/MINOR is different, update the Configuration File and place it on the SD card root

4. Power on the device and wait for the upgrade process to complete

Note: An incompatible firmware image is deleted and does not break the device

Example: Current firmware: 01.01.01, new firmware: 01.01.02

1. Download firmware-01.01.02.zip and unzip it

2. Copy firmware.bin to the SD card

3. The MAJOR and MINOR versions are unchanged (no need to update the Configuration File)


Example: Current firmware: 01.01.00, new firmware: 01.02.00

1. Download firmware-01.02.00.zip and unzip it

2. Copy firmware.bin to the SD card

3. Update the Configuration File (or use the default created by the firmware update)


0.8.3.4 Upgrade over-the-air

See the remote access section

0.8. Firmware 69

canedge2docs - css electronics

Documents