CANedge1 Docs

Release FW 01.06.04

Apr 12, 2022

 CONTENTS

0.1 CANedge1 documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

0.1.1 About this manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
0.1.2 Legal information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
0.2 Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
0.2.1 CAN-bus (x2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
0.2.2 LIN-bus (x2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
0.2.3 Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
0.2.4 Real-time clock (RTC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
0.2.5 Electrical . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
0.2.6 Mechanical . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
0.2.7 Connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
0.3 Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
0.3.1 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
0.3.2 Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
0.3.3 Enclosure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
0.3.4 SD card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
0.3.5 LED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
0.3.6 Label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
0.4 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
0.4.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
0.4.2 Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
0.4.3 Real-Time-Clock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
0.4.4 Secondary port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
0.4.5 CAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
0.4.6 LIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
0.5 Device file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
0.6 Log file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
0.6.1 Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
0.6.2 MDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
0.6.3 Generic header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
0.7 Remote access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
0.7.1 Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
0.7.2 Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
0.7.3 Managing devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
0.7.4 Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
0.8 Firmware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
0.8.1 Firmware download . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
0.8.2 Firmware versioning & naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
0.8.3 Firmware upgrade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

i
ii
 CANedge1 Docs, Release FW 01.06.04

0.1 CANedge1 documentation

0.1.1 About this manual

0.1.1.1 Purpose

This manual describes the functionality of the CANedge1 (firmware 01.06.04) with focus on:
1. Hardware & installation
2. Configuration
3. Firmware upgrade
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 also
detail 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 equal
101010102 = 17010 = 𝐴𝐴16 ). However, it is sometimes more convenient to represent the number using a
specific base.

0.1. CANedge1 documentation 1

CANedge1 Docs, Release FW 01.06.04

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 CAN
bus system.
Improper installation or usage of the device can lead to serious malfunction, loss of data, equipment
damage and physical injury. This is particularly relevant when the device is physically connected to
a CAN based application that may be controlled via the CAN bus. In this setup you can potentially
cause an operational change in the system, turn on/off certain modules and functions or change to an
unintended mode.
While the device supports a high degree of security in regards to wireless data transfer and over-the-air
updates, it is recommended that these features are used with caution. Incorrect usage of this functionality
can 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 understand
how 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.
The device is in conformity with all provisions of Annex II of Council Directive 2014/30/EU, in its latest
amended 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 interference
received, 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 according
to CAN/CSA CISPR 22-10.
Specifically, it is in conformity with the following standards:

EN 55032:2015 - Electromagnetic Compatibility of Multimedia Equipment

EN 55024:2010+A1:2015 - IT equipment. Immunity characteristics. Limits and methods of␣
˓→measurement

FCC Rules and Regulations Part 15 Subpart B: 2018

ICES-003: Issue 6 January 2016

0.1.2.4 Voltage transient tests

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

2 CONTENTS
 CANedge1 Docs, Release FW 01.06.04

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

ISO 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 Electronics
EU VAT ID: DK36711949
Soeren Frichs Vej 38K (Office 35), 8230 Aabyhoej, Denmark
contact[AT]csselectronics.com
+45 91252563
www.csselectronics.com

0.1. CANedge1 documentation 3

CANedge1 Docs, Release FW 01.06.04

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, 4M
2 Bit-rate list: 5k, 10k, 20k, 33.333k, 47.619k, 50k, 83.333k, 95.238k, 100k, 125k, 250k, 500k, 800k, 1M
3 Bit-rate list: 5k, 10k, 20k, 33.333k, 47.619k, 50k, 83.333k, 95.238k, 100k, 125k, 250k, 500k, 800k, 1M, 2M, 4M
4 The device logs raw data frames

4 CONTENTS
 CANedge1 Docs, Release FW 01.06.04

– 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

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
– 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
5 Data lengths are defined by bits 4 and 5 of the LIN identifier
6 See the performance tests
7 The device is supplied from connector 1 (CH1)
8 Up to 24V
9 The transient voltage protection is designed to clamp low energy voltage events. High energy voltage events may

overheat and destroy the input protection

10 Can be used to supply external devices
11 The 5V output can be used to power WiFi hotspots, sensors, small actuators, external LEDs, etc.

0.2. Specification 5
CANedge1 Docs, Release FW 01.06.04

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

See the CANedge2 for wireless data transfer.

12 Without external antenna

6 CONTENTS
 CANedge1 Docs, Release FW 01.06.04

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 protected
against low energy voltage events which can be expected as a result of supply wire noise, ESD and
stub-wire inductance.
If the supply line is shared with inductive loads, care should be taken to ensure high energy voltage events
do 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, fuel
injectors etc. The internal protection circuitry of the device is not capable of handling high energy
voltage 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 within
range, 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 ground
potentials 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-tail
be 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 these
are 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 length
from 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.

0.3. Hardware 7
CANedge1 Docs, Release FW 01.06.04

Warning: Opening the enclosure can permanently damage the device due to e.g. ESD (electrostatic
discharge) - 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 rating
of 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).

Hardware revision ≥ 00.01

Pin # Channel 1 (CH1) Channel 2 (CH2)

1 NC 5V Supply Output
2 CAN 1 L CAN 2 L
3 GND GND
4 LIN Data 1 LIN Data 2
5 NC NC
6 GND (optional) GND (optional)
7 CAN 1 H CAN 2 H
8 NC NC
9 Supply & LIN1 VBAT LIN2 VBAT

Hardware revision = 00.00

The hardware 00.00 pinout can be found here.

8 CONTENTS
 CANedge1 Docs, Release FW 01.06.04

Supply

The supply (CH1 pin 9) is used to power the device. The supply is internally protected against reverse
polarity 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 device
limits

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 device
configuration. 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 are
connected to the 5V Supply Output

CAN L/H

Warning: CAN-bus requires no common reference (ground). However, it is recommended that

GND (ground) is carried along with CAN-L/H to prevent that the common-mode voltage is exceeded
(resulting in transceiver damage)

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.

0.3. Hardware 9
CANedge1 Docs, Release FW 01.06.04

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 in
the 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 few
seconds 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.json
schema-XX.XX.json
device.json
LOG/
[DEVICE_ID]
00000001
00000001.MF4
00000002.MF4
...
...
00000002
00000001.MF4
00000002.MF4
...
...
...
...

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

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

10 CONTENTS
 CANedge1 Docs, Release FW 01.06.04

• 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]. For

more 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 to
ensure 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 provided
with the CANedge have the following guaranteed minimum endurance numbers1 :

Size [GB] TBW Lifetime @ 1MB/sec [years]2 Lifetime @ 1MB/min [years]

8 24 0.8 47.9
32 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.
1 TBW: Terabytes Written
2 A constant logging rate of 1 MB/sec is likely much much higher than in any practical logging use-case

0.3. Hardware 11
CANedge1 Docs, Release FW 01.06.04

0.3.5.2 Overview

LED Short Name LED Color Main Function

PWR Green Power
CH1 Yellow Bus activity on connector 1
(CH1)
CH2 Yellow Bus activity on connector 2
(CH2)
MEM Red Memory card activity

PWR

The Power LED is constantly on when the device is in normal operation. An exception is when the
firmware 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, file
upload etc. all generate activity on the memory card.

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

12 CONTENTS
 CANedge1 Docs, Release FW 01.06.04

The label holds the following information:

• Device type: CANedge1
• Production data in format YYYYWW (WW = week number): 201930
• Hardware version: 00.00
• Unique device ID: EA9B650D
• Data matrix (ECC200) containing production date and device ID: 201930;EA9B650D;
XXXXXXXXXXXX

0.3. Hardware 13
CANedge1 Docs, Release FW 01.06.04

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 length

string 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.

Type Min length Max length

string 0 100

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 information
logged. Should only be enabled if needed during installation or troubleshooting.

Type Default Options

integer 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 for
implementing 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

14 CONTENTS
 CANedge1 Docs, Release FW 01.06.04

the same shared secret, without exposing any secrets. The shared secret is in turn used to generate a
symmetric 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 initialization
vector (iv) and cipher text (ct) are concatenated (iv + ct), base64 encoded and stored in the

0.4. Configuration 15
CANedge1 Docs, Release FW 01.06.04

configuration file

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

Note: By storing the symmetric key it is possible to change specific protected fields - without updating
the 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 basic
code sample to illustrate how Python can be used to encrypt plain-text data. The example code is tested
with Python 3.7.2 and requires the pycryptodome crypto library:
Python example code

0.4.2 Logging

This page documents the logging configuration

0.4.2.1 Configuration file fields

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 Maximum

integer 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 new
file 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 of

integer 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 of

integer 0 0 86400 10

16 CONTENTS
 CANedge1 Docs, Release FW 01.06.04

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 Options

integer 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 to
processing.

Type De- Options

fault
inte- 0 Disable: 0 256 bytes window: 256 512 bytes window: 512 1024 bytes window:
ger 1024

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

Type Default Options

integer 0 Disable: 0 Enable: 1

Error Frames log.error_frames

State log.error_frames.state
Specify whether to record error frames. Enabling this can negatively impact performance, as a potentially
large number of additional frames may be recorded.

Type Default Options

integer 0 Disable: 0 Enable: 1

0.4.2.2 Configuration explained

This section contains additional information and examples.

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

0.4. Configuration 17
CANedge1 Docs, Release FW 01.06.04

• 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 on
heatshrink. Compressed files will have *.MFC as file extension. A high window size improves compression
rates, 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 CANedge
Intro).

Note: The split size set in split_size considers the size of the compressed data. I.e. if the split size
is 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 encryption
scheme 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 (see
the CANedge Intro).

Error Frames

Enabling error frames will log errors across all interfaces, both CAN and LIN. Note that this can decrease
the 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 resume
3 Compressed size in percentage of original. Lower is better.

18 CONTENTS
 CANedge1 Docs, Release FW 01.06.04

0.4.3 Real-Time-Clock

This page documents the real-time-clock configuration

0.4.3.1 Configuration file fields

This section is autogenerated from the Rule Schema file.

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 is
off.

Type Default Options

integer 0 Retain current time: 0 Manual update: 1

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 Maximum

integer 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 Maximum

integer 0 -129600 129600

0.4.3.2 Configuration explained

This section contains additional information and examples.

The CANedge uses a real-time clock (RTC) with battery backup, which allows it to retain the absolute
date & time when the device is not powered. The RTC enables the CANedge to add absolute timestamps
to 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 retainedor manually set.

Manual update

Manually changing the RTC is only needed if the RTC time is completely lost (e.g. after a battery
replacement). 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

0.4. Configuration 19
CANedge1 Docs, Release FW 01.06.04

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

0.4.4 Secondary port

This page documents the secondary port configuration

0.4.4.1 Configuration file fields

This section is autogenerated from the Rule Schema file.

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

Type Default Max items

array [] 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 Default
string 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 Default
string 00:00

0.4.4.2 Configuration explained

This section contains additional information and examples.

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 and
12:00-16:00. Secodary port configuration:

"secondaryport": {
"power_schedule": [
{
"from": "00:00",
"to": "04:00"
(continues on next page)

20 CONTENTS
 CANedge1 Docs, Release FW 01.06.04

(continued from previous page)

},
{
"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

This section is autogenerated from the Rule Schema file.

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.

Type Default Options

integer 1 Disable: 0 Enable: 1

Transmission (tx) initial state can.general.tx_state

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

Type Default Options

integer 1 Disable: 0 Enable: 1

Configuration explained

This section contains additional information and examples.

0.4.5.2 Physical

This page documents the physical configuration

0.4. Configuration 21
CANedge1 Docs, Release FW 01.06.04

Configuration file fields

This section is autogenerated from the Rule Schema file.

Mode can.phy.mode
Device CAN bus mode. Configures how the device interacts with the bus. In Normal mode, the device can
receive, 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 transmit
frames. It is recommended to always use the most restrictive mode possible.

Type De- Options

fault
inte- 1 Normal (receive, acknowledge and transmit): 0 Restricted (receive and acknowledge):
ger 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.

Type Default Options

integer 1 Disable: 0 Enable: 1

CAN FD specification can.phy.fd_spec

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

Type Default Options

integer 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-rate
manually if it is known.

Type Default Options

integer 0 Auto-detect: 0 Bit-rate (simple): 1 Bit-timing (advanced): 2

Configuration explained

This section contains additional information and examples.

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%

22 CONTENTS
 CANedge1 Docs, Release FW 01.06.04

Bitrate BRP Quanta Seg1 Seg2 SJW

5k 100 80 63 16 4
10k 50 80 63 16 4
20k 25 80 63 16 4
33.333k 10 120 95 24 4
47.619k 8 105 83 21 4
50k 10 80 63 16 4
83.333k 4 120 95 24 4
95.238k 4 105 83 21 4
100k 5 80 63 16 4
125k 4 80 63 16 4
250k 2 80 63 16 4
500k 1 80 63 16 4
800k 1 50 39 10 4
1M 1 40 31 8 4
2M 1 20 15 4 4
4M 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 possible
to 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 can
be used to calculate the bit-timing fields:
480000000
• Input clock: 𝐶𝐿𝐾 = 12 = 40000000 = 40MHz
• Quanta: 𝑄 = 1 + 𝑆𝐸𝐺1 + 𝑆𝐸𝐺2
𝐶𝐿𝐾/𝐵𝑅𝑃
• Bit-rate: 𝐵𝑅 = 𝑄
1+𝑆𝐸𝐺1
• Sample point: 𝑆𝑃 = 100 · 𝑄

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, the
number of quanta is calculated as:

𝐶𝐿𝐾/𝐵𝑅𝑃 40000000/1
𝑄= = = 20
𝐵𝑅 2000000

0.4. Configuration 23
CANedge1 Docs, Release FW 01.06.04

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

𝑆𝑃 · 𝑄 75 · 20
𝑆𝐸𝐺1 = −1= = 14
100 100
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

Configuration file fields

This section is autogenerated from the Rule Schema file.

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, remote
request frames are discarded before they reach the message filters.

Type Default Options

integer 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-bit
filters and 64 29-bit filters.

Type Min items Max items

array 1 192

Item can.filter.id.item
Name can.filter.id.item.name
Optional filter name.

Type Max length

string 16

State can.filter.id.item.state
Disabled filters are ignored.

Type Default Options

integer 1 Disable: 0 Enable: 1

Type can.filter.id.item.type

24 CONTENTS
 CANedge1 Docs, Release FW 01.06.04

Action on match, accept or reject message.

Type Default Options

integer 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 Options

integer 0 Standard (11-bit): 0 Extended (29-bit): 1

Filter method can.filter.id.item.method

The filter ID matching mechanism.

Type Default Options

integer 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 defines
the filter ID.

Type Default Max length

string 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 defines
the filter mask.

Type Default Max length

string 7FF 8

Configuration explained

This section contains additional information and examples.

The following uses a mix of binary, decimal and hexadecimal number bases. For more information on
the 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.

0.4. Configuration 25
CANedge1 Docs, Release FW 01.06.04

Messages matching no filters are rejected as default. Note that the default Configuration File has filters
that 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 are
not 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 matching
filter element determines if a message is accepted or rejected. Acceptance and Rejection filters can be
combined to generate a complex message filtering mechanism.
Example: A message matches acceptance filter 3. Rejection filter 4 is not evaluated. The message is
accepted.

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

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. Message
IDs within the range (both start and end included) pass the filter.
Example: Standard ID filter with range from = 1, to = 10:

26 CONTENTS
 CANedge1 Docs, Release FW 01.06.04

ID format ID (DEC) Pass

Standard 0 No
Standard 1 Yes
Standard 10 Yes
Standard 11 No
Extended 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 . The
filter ID is set to the value of the message ID to accept. The filter mask is set to all ones, such that all
bits of the filter are considered, as given in (1).

Filter ID 111110100002 Message ID 111110100002

Filter mask &111111111112 (1) Filter mask &111111111112 (2)
Masked filter 111110100002 Masked ID 111110100002

To test if the message passes the filter, we apply the filter mask to the message ID as given in (2). The
masked 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 which
accepts both IDs, we can use the mask field to mask out the rightmost bit - such that it is not considered
when the filter is applied. In (1) the mask is set such that the rightmost bit is not considered (indicated
by red color).

Filter ID 111110100002 Message ID 111110100012

Filter mask &111111111102 (1) Filter mask &111111111102 (2)
Masked filter 111110100002 Masked ID 111110100002

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 both
111110100002 and 111110100012 passes the filter, as the rightmost bit is not considered by the filter (the
rightmost 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 of
the 29 bits. The remaining 11 bits define the priority and source address of the message. It is often
useful 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 bits
the 8-bit source address of the 29-bit CAN-ID.

000111111111111111111000000002 = 3FFFF0016
1 & is used as the bitwise AND operation

0.4. Configuration 27
CANedge1 Docs, Release FW 01.06.04

Message ID bits in positions with zero bits in the filter mask are ignored. By using 3FFFF0016 as filter
mask, the source and priority are ignored.
To specifically accept PGN 61444 F00416 messages, the message ID is set to F0040016 - note the the
final 8-bit 0016 represents the source address which is ignored by the filter mask (these bits can be set
to any value).
Filter mask 3FFFF0016 can be used for all J1939 PGN messages. To accept specific PGNs, the message
ID is adjusted. To accept one specific PGN (as in the example above), the message ID is set to the
specific 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 is
setup 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 Range
filtering. 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), then
proccessed by the acceptance filter (accepts all message in range). If none of the filters
pass/match, the default behavior is to reject the message. It is in this case important that
the rejection filter is placed before the acceptance filter in the list (processing stops on first
match).
Filter list test table:

Message ID Filter elm 1 Filter elm 2 Result

49810 Ignore Ignore Reject
49910 Reject Reject
50010 Ignore Accept Accept
50110 Reject Reject
99910 Reject Reject
100010 Ignore Accept Accept
100110 Reject Reject
100210 Ignore Ignore Reject

28 CONTENTS
 CANedge1 Docs, Release FW 01.06.04

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 assigned
a mixture of prescaler types.
Applying filters can dramatically reduce log file size, resulting in prolonged offline logging and reduced
data 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 first
100 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 (prescaling
value). A prescaling value of 2 accepts every 2nd message (with a specific ID), a value of 3 every 3rd
and so on up to 2562 .
Count prescaling applied to ID 60010 with a scaling value of 3

ID (DEC) ID occurrences Result

60010 1 Accept
60010 2 Reject
60010 3 Reject
60010 4 Accept
60010 5 Reject

Time

Time prescaling sets a lower limit on time interval (period time) of a specific message ID. This is done
by rejecting messages until at least the prescaler time has elapsed3 . The prescaler timer is reset each
time 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 broadcasted
on the CAN-bus at a high frequency5 .
Example: A slowly changing temperature measurement broadcasted every 10 ms (100Hz). Prescaled to
a minimum time interval of 100ms (prescaler value set to 100).
2 A scaling factor of 1 effectively disables prescaling
3 Note that messages are not resampled to a specific fixed period time
4 It is not possible to do sub-millisecond time prescaling
5 Higher frequency than needed to get a good representation of the signal content

0.4. Configuration 29
CANedge1 Docs, Release FW 01.06.04

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

ID (DEC) Message timestamp Prescaler timer [ms] Result

[ms]
70010 200 0 Accept
70010 700 500 Reject
70010 1000 800 Reject
70010 1200 1000 -> 0 (reset) Accept
70010 1300 100 Reject
70010 3200 2000 -> 0 (reset) Accept
70010 4200 1000 -> 0 (reset) Accept
70010 5200 1000 -> 0 (reset) Accept

Data

Data prescaling can be used to only accept messages when the data payload changes. A mask can be
set to only consider changes in one or more specific data bytes. The mask works on a byte level. The
mask is entered in hex up to 8 bytes long (16 hex characters). Each byte contains 8 bits, allowing for
the 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 additional
bytes are ignored by the prescaler.

30 CONTENTS
 CANedge1 Docs, Release FW 01.06.04

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

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

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

ID (DEC) D0 D1 D2 D3 Result
80010 00 11 22 33 Accept
80010 00 11 22 33 Reject
80010 00 BB 22 33 Accept
80010 AA BB 22 33 Accept
80010 AA BB 22 DD Accept
80010 AA BB 22 DD Reject

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

ID (DEC) D0 D1 D2 D3 Result
80010 00 11 22 33 Accept
80010 00 11 22 33 Reject
80010 00 BB 22 33 Reject
80010 AA BB 22 33 Accept
80010 AA BB 22 DD Reject
80010 AA BB 22 DD Reject

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

ID (DEC) D0 D1 D2 D3 Result
80010 00 11 22 33 Accept
80010 00 11 22 33 Reject
80010 00 BB 22 33 Reject
80010 AA BB 22 33 Reject
80010 AA BB 22 DD Accept
80010 AA BB 22 DD Reject

0.4. Configuration 31
CANedge1 Docs, Release FW 01.06.04

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

ID (DEC) D0 D1 D2 D3 Result
80010 00 11 22 33 Accept
80010 00 11 22 33 Reject
80010 00 BB 22 33 Reject
80010 AA BB 22 33 Accept
80010 AA BB 22 DD Accept
80010 AA BB 22 DD Reject

0.4.5.4 Transmit

This page documents the transmit configuration.

Configuration file fields

This section is autogenerated from the Rule Schema file.

Transmit messages can.transmit
List of CAN bus messages transmitted by the device. Requires a CAN-bus physical mode supporting
transmissions.

Type Max items

array 64

Item can.transmit.item
Name can.transmit.item.name
Optional transmit message name.

Type Max length

string 16

State can.transmit.item.state
Disabled transmit messages are ignored.

Type Default Options

integer 1 Disable: 0 Enable: 1

ID Format can.transmit.item.id_format
ID format of the transmit message.

Type Default Options

integer 0 Standard (11-bit): 0 Extended (29-bit): 1

Frame format can.transmit.item.frame_format

Frame format of the transmit message.

Type Default Options

integer 0 Standard: 0 Standard RTR: 2 FD: 1

32 CONTENTS
 CANedge1 Docs, Release FW 01.06.04

Bit-Rate Switch can.transmit.item.brs

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

Type Default
integer 0

Include in log can.transmit.item.log

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

Type Default Options

integer 0 Disable: 0 Enable: 1

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 of

integer 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 by
the 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 of

integer 0 4294967290 10

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

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

Type
string

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.

Type Max length

string 128

Configuration explained

This section contains additional information and examples.

Period and delay

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

0.4. Configuration 33
CANedge1 Docs, Release FW 01.06.04

0.4.5.5 Heartbeat

This page documents the heartbeat configuration

Configuration file fields

This section is autogenerated from the Rule Schema file.

State can.heartbeat.state
Enable to periodically transmit heartbeat signal.

Type Default Options

integer 0 Disable: 0 Enable: 1

ID Format can.heartbeat.id_format
ID format of heartbeat message.

Type Default Options

integer 1 Standard (11-bit): 0 Extended (29-bit): 1

ID (hex) can.heartbeat.id
ID of heartbeat message in hex. Example: 1FF.

Type Default
string 00435353

Configuration explained

This section contains additional information and examples.

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-7

Interpretation 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:

34 CONTENTS
 CANedge1 Docs, Release FW 01.06.04

– 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-7

Interpretation Fixed State Epoch time Space left
Payload 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-7

Interpretation Fixed State Epoch time Space left
Payload 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

Configuration file fields

This section is autogenerated from the Rule Schema file.

Control can.control
Control signal
Control reception (rx) state can.control.control_rx_state
Control CAN-bus reception state (including logging)

Type Default Options

integer 0 Disable: 0 Enable: 1

Control transmission (tx) state can.control.control_tx_state

Control CAN-bus transmission state (including logging)

Type Default Options

integer 0 Disable: 0 Enable: 1

Start signal can.control.start

0.4. Configuration 35
CANedge1 Docs, Release FW 01.06.04

ID Format can.control.start.id_format
ID format of the control message.

Type Default Options

integer 1 Standard (11-bit): 0 Extended (29-bit): 1

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

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

Type Default
string 00435354

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

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

Type Default
string 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 length

string FFFFFFFFFFFFFFFF 16

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

Data trigger high range (byte 0 to the left)

Type Default Max length

string 0100000000000000 16

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

Data trigger low range (byte 0 to the left)

Type Default Max length

string 0000000000000000 16

Stop signal can.control.stop

ID Format can.control.stop.id_format
ID format of the control message.

Type Default Options

integer 1 Standard (11-bit): 0 Extended (29-bit): 1

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

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

Type Default
string 00435354

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

36 CONTENTS
 CANedge1 Docs, Release FW 01.06.04

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

Type Default
string 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 length

string FFFFFFFFFFFFFFFF 16

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

Data trigger high range (byte 0 to the left)

Type Default Max length

string 0100000000000000 16

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

Data trigger low range (byte 0 to the left)

Type Default Max length

string 0000000000000000 16

Configuration explained

This section contains additional information and examples.

The control signal has a flexible configuration allowing for integration with many protocols. The control
signal 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 logging
based 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 messages
with 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 allows
for 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 additional
log 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

0.4. Configuration 37
CANedge1 Docs, Release FW 01.06.04

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 two
CAN-bus channels. Channel 1 is configured to start / stop message reception based on the OBD speed
response. 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 goes
above 10 km/h and stops below 5 km/h. Channel 2 is shown for reference (no control signal).

38 CONTENTS
 CANedge1 Docs, Release FW 01.06.04

Example: Start / stop on simple discrete value. In this example the start / stop is controlled via a single
byte.
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 is
moving.
Start trigger:
• High: 000007000000000016 ⇒ 7 km/h
• Low: 000003000000000016 ⇒ 3 km/h
Stop trigger:
• High: 000001000000000016 ⇒ 1 km/h

0.4. Configuration 39
CANedge1 Docs, Release FW 01.06.04

• 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. The
detected 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 the
CAN-bus. The node can be in one of three states:
1. Active

40 CONTENTS
 CANedge1 Docs, Release FW 01.06.04

2. Passive
3. Off
The transitions between the states depends on the number of detected errors in a sliding window. In
the active state, the node is allowed to emit error frames onto the CAN-bus, while any detected error
frames are kept internal in the passive state. In the off state the node is no longer receiving from or
transmitting 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 Monitoring

State Active Passive Active Passive Active Passive
Receive X X X
Transmit X
Acknowledge X X
Internal error frames X X X X X X
External 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 condition
has been detected. As such, all logged error frames have no information about the associated CAN frame
ID/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 violation
of 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 error
need not be a bit-stuffing error, but since another node has detected an error, it will signal this to the
rest 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 more
informative 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 CAN
frame.

CRC Errors

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

0.4. Configuration 41
CANedge1 Docs, Release FW 01.06.04

Bit Errors

When a node is transmitting a frame onto the CAN-bus, it can simultaneously sense what the actual
value 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 to
acknowledge the reception by filling a part of the frame. If no acknowledge is detected, the device raises
an acknowledge error.
Example: If a node transmits a frame onto the bus and no other node acknowledges this via the ACK
segment of the frame, that node will detect a missing acknowledge error. As a response, it will emit an
error 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, 16
error frames can be logged in rapid succession, as the node attempts to re-transmit the frame. After
16 attempts, the internal error counter of the transmitting node has reached 8 * 16 = 128, and the
node enters the passive error state. The transmitting node is still detecting an error, as no other node
acknowledges 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 nodes
on the bus will now log the intended message, even though it is in an erroneous state due to the lack of
acknowledgement.

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

Configuration file fields

This section is autogenerated from the Rule Schema file.

Mode lin.phy.properties.mode
Device LIN bus mode.

Type Default Options

integer 0 Subscriber: 0 Publisher: 1

Bit-rate lin.phy.properties.bit_rate

Type Default Options

integer 19200 2400: 2400 9600: 9600 10400: 10400 19200: 19200

Configuration explained

This section contains additional information and examples.

42 CONTENTS
 CANedge1 Docs, Release FW 01.06.04

0.4.6.2 Frame Table

This page documents the frame table configuration

Configuration file fields

This section is autogenerated from the Rule Schema file.

Name lin.frames.items.name
Optional frame name.

Type Max length

string 16

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

ID of frame in hex. Example: 0F.

Type Max length

string 2

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

Length of the frame in decimal.

Type Minimum Maximum

integer 1 8

Checksum Type lin.frames.items.checksum_type

Type of the checksum used on the LIN frame.

Type Default Options

integer 0 Enhanced: 0 Classic: 1

Configuration explained

This section contains additional information and examples.

The LIN controller expects default data lengths and checksums as explained in LIN . LIN-frames using
a 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 frame
table.

0.4.6.3 Transmit

This page documents the transmit configuration

0.4. Configuration 43
CANedge1 Docs, Release FW 01.06.04

Configuration file fields

This section is autogenerated from the Rule Schema file.

Name lin.transmit.items.name
Optional transmit rule name.

Type Max length

string 16

State lin.transmit.items.state
Disabled transmit rules are ignored.

Type Default Options

integer 1 Disable: 0 Enable: 1

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

Type Max length

string 2

Data (hex) lin.transmit.items.data

Type Max length

string 16

Configuration explained

This section contains additional information and examples.

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 the
data 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 a
different concept than what is used by LDF files.

44 CONTENTS
 CANedge1 Docs, Release FW 01.06.04

Subscriber mode

In Subscriber mode, the CANedge awaits a SUBSCRIBE frame with a matching ID from the bus
Publisher 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 entry
is used.

0.4.6.4 Topology

A LIN-bus consists of a Publisher node and one or more Subscriber nodes. The Publisher controls
scheduling 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 transmits
both the message ID and data, or a SUBSCRIBE message, where the Publisher node only emits the
message 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 each
PUBLISH message is filled with data by the Publisher, while each SUBSCRIBE message has a node
connected 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 of
messages on the network has to be done through the transmit configuration for the interface. Since only
static data can be entered in the configuration, the simple Publisher node emulation cannot perform
dynamic 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 always
defined by the message ID (bits 5 and 6 of the identifier), as defined in the table below:

Message ID Data length

00-31 (0x00-0x1F) 2
32-47 (0x20-0x2F) 4
48-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 except
ID 0x3C and 0x3D will use enhanced checksum. This can be overridden on a frame by frame basis in

0.4. Configuration 45
CANedge1 Docs, Release FW 01.06.04

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 detected
errors 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 checksum
information 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 in
the LIN message on the bus. This can be an indicator of wrong configuration for the frame ID in the
CANedge frame table.
Example: In case no information is known about the LIN bus in advance, the default frame table can
be used with error logging enabled to help reverse engineer the actual frame table. Any message IDs
deviating from the standard table (and present on the LIN-bus) will get a logged entry. These IDs can
then 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 valid
configuration.

Receive Errors

Receive errors are logged when a fixed part of the LIN message is not as expected, or that the node
detects 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 that
there is a too large deviation between the configured bitrate for the node and the detected bitrate from
the synchronization field.

Transmission Errors

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

46 CONTENTS
 CANedge1 Docs, Release FW 01.06.04

0.5 Device file

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

{
"id": "4F07A3C3",
"type": "0000001D",
"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"
}

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

0.5. Device file 47

CANedge1 Docs, Release FW 01.06.04

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 .MFC
X .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 a
binary format which allows compact storage of huge amounts of measurement data. It is specifically
designed for bus frame logging across e.g. CAN-bus, LIN-bus and Ethernet. MDF4 is widely adopted
by 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

48 CONTENTS
 CANedge1 Docs, Release FW 01.06.04

Timestamps

Each record is timestamped with 50 us resolution.

Finalization & sorting

The CANedge stores log files as unfinalized and unsorted to enable power safety. Finalization3 and
sorting4 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 in
the 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 visualized
by the table below.
3 The MDF file header includes information on how to finalize the MDF file before use
4 Sorting refers to an organization of the log records which enable fast indexing. It is not related to sorting of timestamps.

0.6. Log file 49

CANedge1 Docs, Release FW 01.06.04

Table 1: Fields for CAN channels

Field name Field description CAN_DataFrame CAN_RemoteFrame CAN_ErrorFrame
Timestamp Relative timestamp X X X
ID CAN ID X X
IDE Extended ID flag X X
BusChannel Hardware channel X X X
Dir Direction (RX/TX) X X
DLC DLC code X X
DataLength Translated DLC code X X
BRS FD Bitrate switch X
EDL FD flag X
ESI FD ESI flag X
DataBytes Data X
ErrorType 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 devoid
of 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 visualized
by the table below. It is possible, though unlikely, for the same LIN frame to trigger multiple errors.

50 CONTENTS
 CANedge1 Docs, Release FW 01.06.04

Table 2: Fields for LIN channels

Field name Field descrip- LIN_ChecksumError
LIN_Frame LIN_ReceiveError
LIN_SynchronizationError
LIN_TransmissionError
tion
Timestamp Relative X X X X X
timestamp
ID ID X X X X
BusChannel Hardware X X X X X
channel
Dir Direction X X
(RX/TX)
DataBytes Data X X
DataLength Number of X X
data bytes
Received- Number of X X
DataByte- data bytes
Count
Checksum Received X
checksum
Checksum- Classi- X
Model cal/Enhanced

For checksum errors, the logged checksum is the one received on the LIN bus. The non-matching
calculated 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 identify
and store relevant information for the files. All file headers consist of a generic 20 byte header, followed
by any specialized fields.
The generic header starts with an identifying sequence of the ASCII code for Generic File5 . Following
are 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 Counter
Mode (GCM), with a file sub-type of 0x01. The current version of the format is 0x00 for both major
and 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 endian
format
• 16 bytes of salt data for the hashing of the key
5 Generic File maps to 12 bytes of ASCII, with no zero termination of the string.

0.6. Log file 51

CANedge1 Docs, Release FW 01.06.04

|<- 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 runs
in GCM mode. When decrypting, this tag should be checked to ensure the validity of the decrypted
data. 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 is
heatshrink based. This is denoted by a file sub-type of 0x01. The current version of the format is 0x00
for both major and minor. The additional header data are two unsigned 32 bit numbers: Lookahead
and 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 data
is 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.

52 CONTENTS
 CANedge1 Docs, Release FW 01.06.04

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 network
application 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 require
internet 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 are
located at two separate networks. Internet connection is used to connect the two local networks and
allow 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

0.7. Remote access 53

CANedge1 Docs, Release FW 01.06.04

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, the
installation 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 time
2 Time needed for a single packet transfer
3 This is particularly the case due to the limited resources of the device

54 CONTENTS
 CANedge1 Docs, Release FW 01.06.04

If multiple servers are available (such as regional cloud server endpoints), make sure to select a server
with 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 the
configuration) 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 the
device 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 used
in 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 is
deleted 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 the
network 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 identical
log files with different EPOCH_TIME timestamps. Copies of the same log file (same SESSION_NUMBER and
SPLIT_NUMBER) should be ignored or removed.

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

0.7. Remote access 55

CANedge1 Docs, Release FW 01.06.04

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 format
YYYYMMDDTHHMMSS
• 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 the
Configuration 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 always
knows the configuration rules of a specific device. If the firmware is updated, the device automatically
uploads 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 Configuraton
File is updated on the server it is automatically downloaded and applied by the device (causing a power
cycle). 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 File
is 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 Firmware
File 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 new
firmware is a MAJOR or MINOR upgrade, an updated Configuration File must also be provided.

56 CONTENTS
 CANedge1 Docs, Release FW 01.06.04

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 Server
Certificate 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 the
SD 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 to
ensure that the device can access a server both before and after the update. It is recommended to
always 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

0.7. Remote access 57

CANedge1 Docs, Release FW 01.06.04

4. Generate a new Server Certificate Bundle without the soon-to-expire certificate and repeat step 2
and 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 Security
Mode 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 High

API credentials X X X
Transport security (TLS) X X
Server identity authentication (TLS) X X
Device 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:

58 CONTENTS
 CANedge1 Docs, Release FW 01.06.04

API credentials

The device uses the server S3 credentials (AccessKey and SecretKey) to calculate an authentication
signature for each request. Upon reception, the server verifies the signature (see the S3 REST API for
details). 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 limited
set of ciphers for communicating with the remote server.

0.7. Remote access 59

CANedge1 Docs, Release FW 01.06.04

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 issue
the 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 with
the 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

60 CONTENTS
 CANedge1 Docs, Release FW 01.06.04

Cipher Group 1 Group 2 Group 3

TLS_RSA_WITH_AES_128_CBC_SHA X X X
TLS_DHE_RSA_WITH_AES_128_CBC_SHA X X X
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA X X X
TLS_RSA_WITH_AES_128_CBC_SHA256 X X
TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 X X
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 X X
TLS_RSA_WITH_AES_128_GCM_SHA256 X
TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 X
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 X

These are divided into 3 groups, with each group containing a larger set of supported ciphers. Connections
will initially be attempted with only group 1. In case the connection attempt fails, the CANedge will
attempt 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 certificate
authority (CA). At the button is the user (application) certificate. In this specific case, the user certificate
is 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 server
must 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 the
trust chain. Self-signed certificates are used directly, as these do not form a trust chain.

0.7. Remote access 61

CANedge1 Docs, Release FW 01.06.04

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 Name
Indication (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 below
shows 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 to

distinguish the certificates

62 CONTENTS
 CANedge1 Docs, Release FW 01.06.04

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 -certfile
certificate_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 to
Server 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 trusted
if 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

0.7. Remote access 63

CANedge1 Docs, Release FW 01.06.04

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 result
in unexpected behavior. The mandatory update sequence is illustrated below.

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 and
certificates 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)
• 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

64 CONTENTS
 CANedge1 Docs, Release FW 01.06.04

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 upgrade
process.

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 File
and 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 modified
Configuration File with a name matching the new version.

Note: The firmware can be upgraded without providing a new compatible Configuration File. In this
case, 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)
4. Power on the device and wait for the upgrade process to complete

0.8. Firmware 65
CANedge1 Docs, Release FW 01.06.04

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)
4. Power on the device and wait for the upgrade process to complete

66 CONTENTS