Differences

This shows you the differences between two versions of the page.

--- ve.can:changing_nmea2000_instances [2020-06-28 21:36] – [5.2 New method - changing Data instance] mvader
+++ ve.can:changing_nmea2000_instances [2025-02-06 22:04] (current) – [1.3 Considerations before changing instances] mvader
@@ Line 3: / Line 3: @@
 ===== 1. Introduction =====
-Instances are used in an NMEA2000 network to identify multiple similar products connected on the same network.
+==== 1.1 Purpose of  NMEA 2000 instances ====
+Instances are used in an NMEA 2000 network to identify multiple similar products connected on the same network.
-As an example, take a system with two battery monitors (one for the main battery bank, and another for the hydraulic-thruster bank) and also a Quattro inverter/charger. All three of those devices will send their battery voltage measurements out on the canbus.
+As an example, take a system with two battery monitors (one for the main battery bank, and another for the hydraulic-thruster bank) and also a Quattro inverter/charger. All three of those devices will send their battery voltage measurements out on the N2K network. For the displays to show these values at the right place, they need to know which voltage belongs to what battery. That is what instances are for.
-For the displays to show these values at the right place, they need to know which voltage belongs to what battery.
-Before going ahead and change instances, please make sure to first study [[https://www.victronenergy.com/live/ccgx:start#marine_mfd_integration_by_nmea_2000|the NMEA2000-out chapter in the GX manual]].
+==== 1.2 Different types of instances ====
-=== How can I change the instances? ===
+There various types of instances, and for marine systems are two that matter: the Device instance and the Data instance. The data instance goes by various different names, like Fluid instance, Battery instance and DC instance.
-This document describes three options:
+Details and differences of each type are explained in detail in the [[https://www.victronenergy.com/media/pg/Cerbo_GX/en/marine-mfd-integration-by-nmea-2000.html|Cerbo GX manual, NMEA 2000 chapter]].
-  - Use [[http://www.actisense.com/|Actisense]] software & hardware. Can change both the device- and data-instances
+==== 1.3 Considerations before changing instances ====
-  - Use [[https://www.maretron.com/|Maretron]] software & hardware. Can change device instance only.
-  - From the commandline of a [[venus-os:start|GX device]]. Note that this is a software developer trick. Not for any day use. Allows changing device instances as well as data instances.
-=== Device instance, data instances and other instances ===
+First of all, note that it is only rarely necessary to change either device or data instances like the Fluid-, Battery- and DC-instance. Other sections in this document explain the specifics per make of MFD brand (Garmin, Raymarine, others).
-There various types of instances, and for marine systems are two that matter in most cases: the Device instance as well as the Data instance. Please make sure to study [[https://www.victronenergy.com/live/ccgx:start#marine_mfd_integration_by_nmea_2000|the NMEA2000-out chapter in the GX manual]] before continuing. It also links to specific instructions for Raymarine, Garmin, Furuno, Simrad, B&G and Lowrance MFDs.
+When it is necessary or required to change instances, then depending on the type of product and system used, changing instances could also affect behaviour of the Victron equipment. In more detail:
-=== Related information ===
+**GX devices, NMEA2000-out feature**
-For more detailed information, see also the FAQ in our [[https://www.victronenergy.com/upload/documents/Whitepaper-Data-communication-with-Victron-Energy-products_EN.pdf|Data communication whitepaper]].
+All instances of the transmitted by a GX device can be set to any value, there is no related functionality. Includes device instances, and data instances.
-And the main [[ve.can:nmea-2000:start|NMEA2000 integration guide]].
+**Other products: Device instance**
-===== 2. Changing the device instance with Actisense =====
+The NMEA 2000 device instance, which is the same as the VE.Can device instance, is by default set to 0 on all Victron products.
+Some products, such as Lynx Smart BMS, Solar chargers with a VE.Can port and Battery chargers with a VE.Can port, have functionality that relates to the device instance. Therefore make sure to read the manual of that product before changing the device instance.
+**Battery chargers: Data instances (Battery- and DC instance)**
+Whilst it is possible to change the Battery and DC instances on a Skylla-i battery charger, changing those will render it impossible for a GX device to properly read the data. This is because the GX device expects the charger's output one to be on Battery & DC instance 0, output two on Battery & DC instance 1, and output three on Battery & DC instance 2.
+==== 1.4 Recommend instancing setup for main MFD brands ====
+The only common use case we encounter in testing and support where it is necessary to change instances is with older Raymarine hardware & software:
+    * Raymarine i70: max number of tank levels is 5; fluid instance 0-4 and type must be fuel.
+    * Raymarine i70s: max number of tank levels is 5; fluid instance 0-4 and type must be fuel.
+    * Axiom MFDs: per Lighthouse version 4.1.75, a maximum of 16 tanks can be connected; fluid instance 0-15.
+Further details per brand are in these documents:
+  * [[venus-os:mfd-raymarine#nmea_2000|NMEA 2000 configuration for Raymarine]]
+  * [[venus-os:mfd-garmin#nmea_2000|NMEA 2000 configuration for Garmin]]
+  * [[venus-os:mfd-furuno#nmea_2000|NMEA 2000 configuration for Furuno]]
+  * [[venus-os:mfd-navico#nmea_2000|NMEA 2000 configuration for Navico (B&G, Simrad and Lowrance]])
+==== 1.5 Different methods for setting up instances ====
+As the NMEA2000 protocol prescribes commands to change an instance by sending commands to a device, there are various ways of changing instances. The purpose of this document is to describe all commonly used methods.
+Besides the here described methods there are more, for example some MFDs allow changing instances as well.
+  - GX Device: Device- instances only
+  - Actisense software + NGT-1 USB: Device- as well as data-instances
+  - Maretron software + USB adapter: Unknown
+  - Commandline of a [[venus-os:start|GX device]]: Device- as well as data-instances. Note that this required advanced Linux skills; and is listed here only for benefit of experienced software developers
+Chapter 2, 3, 4, 5 and 6 explain these methods in detail.
+==== 1.6 Further reading on Victron and NMEA 2000 ====
+  * [[ve.can:nmea-2000:start]]
+  * [[https://www.victronenergy.com/upload/documents/Whitepaper-Data-communication-with-Victron-Energy-products_EN.pdf|Data communication white paper]]
+  * [[https://www.victronenergy.com/media/pg/Cerbo_GX/en/marine-mfd-integration-by-nmea-2000.html|Cerbo GX manual, NMEA 2000 chapter]]
+  * [[https://community.victronenergy.com/topics/NMEA%202000%20-%20N2K.html|NMEA2000 related discussions on Victron Community]]
+===== 2. GX Device: changing device instances =====
+The Settings -> Services -> VE.Can -> Devices menu shows a list of all devices on the N2K / VE.Can network:
+{{  :ve.can:device_instance_gx.png?direct&400 |}}
+By clicking the right button, a detailed menu is shown:
+{{  :ve.can:device_instance_detail_menu.png?direct&400 |}}
+===== 3. Actisense: changing device instances =====
 Note: make sure to use a recent Actisense driver. Otherwise the instance might not ‘stick’.
@@ Line 44: / Line 96: @@
 {{:ve.can:device_instance.png?direct&}}
-===== 3. Changing a data instance with Actisense =====
+===== 4. Actisense: changing data instances =====
 Requires the [[http://www.actisense.com/product/nmea-2000-to-pc-interface-ngt-1/|Actisense NGT-1]].
-Changing a data instance:
+Step by step instructions:
   - Open Actisense NMEA Reader
   - Select data view (tab selection is at the bottom left)
-  - Right click on the PGN number. Note that this will only work on PGNs that allow changing their data instance: \\ {{:ve.can:data_instance_0.png?direct&}}
+  - Right click on the PGN number. Note that this will only work on PGNs that allow changing their data instance (first screenshot below)
-  - And change the value: \\ {{:ve.can:data_instance_1.png?direct&}}
+  - And change the value (second screenshot below)
-Notes for BMVs, Lynx Shunt and the Lynx Ion + Shunt:
+Notes:
+  * The Battery Instance and the DC instance are the same value within Victron products. Changing one of them, will also change the other one.
-  * The Battery Instance and the DC Detailed instance are the same value. Changing one of them, will also change the other one.
   * Since the BMV sends out two voltages, the main voltage and the aux- or starter-voltage, it comes preconfigured with two battery instances: 0 and 1. When you want to change that to 1 and 2, change the 1 into 2 first, and then the 0 into 1, as they cannot be the same.
+  * Changing the fluid level instance using Actisense has a bug. Probably due Actisense seeing it as 8 bit number; while in the definition it is a 4 bit number. Work around: using the GX, set the fluid type to Fuel (0), then using Actisense change the fluid instance to the desired value, and then using your GX, set the type back to the desired type.
+{{:ve.can:data_instance_0.png?direct&}}
-===== 4. Changing Instance Using Maretron N2KAnalyzer =====
+{{:ve.can:data_instance_1.png?direct&}}
-Maretron uses a term called "Unique Instance" where the N2KAnalyzer software tool automatically determines if a particular device uses device or data instances.
-WARNING: At Victron we do not understand what and how the Maretron software works with regards to this. We advise to use another tool, not Maretron, so that you know what you are doing, ie know what instance you are changing. So far, we have not been able to use Maretron software to change a data instance. And changing the other instance, the device instance can also be done straight from the Victron GX device its user interface. To change a data instance, for example to fix instance conflicts as reported by the Maretron software, we recommend to use Actisense. Not Maretron.
-This procedure requires a Maretron USB adapter.
+===== 5. Maretron N2KAnalyzer =====
-Open N2KAnalyzer and make sure that the "Unique Instance" column is turned on (i.e. checked) using the Setup>Columns menu item.
+Maretron uses a term called "Unique Instance" where the N2KAnalyzer software tool automatically determines if a particular device uses device or data instances.
-{{:ve.can:maretronn2kanalyzeruniqueinstancecolumn.jpg?850|}}
+WARNING: At Victron we do not understand what and how the Maretron software works with regards to this. We advise to use another tool, not Maretron, so that you know what you are doing, ie know what instance you are changing.
+So far, we have not been able to use Maretron software to change a data instance. And changing the other instance, the device instance can also be done straight from the Victron GX device its user interface. To change a data instance, for example to fix instance conflicts as reported by the Maretron software, we recommend to use Actisense. Not Maretron.
-Within the N2KAnalyzer main window, any cell with a white background can be edited by clicking in the cell and typing in the desired value. You can see from the following screen shot that a few parameters have a white background including Label and Installation Description #1. To change a devices instance, click in the Unique Instance cell for the device you want to change and type the new number followed by a carriage return. If the particular products accepts the instance change, you will see the new instance number reflected in the cell. You can also use a tool within N2KAnalyzer to check that all products on the network are uniquely instanced. Use the Analyze>Instancing menu to verify correct overall system instancing.
+===== 6. Changing the instances from the GX command line =====
-{{:ve.can:maretronn2kanalyzeranalyzeinstancing.jpg?850|}}
+==== 6.1 Introduction ====
-===== 5. Changing the instances from the GX command line =====
-==== 5.1 Introduction ====
 Instead of using Actisense or Maretron software, it is also possible to change the VE.Can aka N2K Device instance from the GX Device shell. To get root access, follow these instructions: [[ccgx:root_access]].
 Once logged into the shell, follow below instructions. More back ground information of the used commands such as dbus and dbus-spy is found by reading about root access document.
-==== 5.1 New method - changing a Device instance ====
+==== 6.2 Warning: better use an Actisense! ====
+Note that the methods explained in this Chapter 6 are usually not recommended. Use an Actisense instead, see chapters 3 and 4 instead.
+==== 6.3 New method - changing a Device instance ====
 All devices available on the canbus are enumerated under the com.victronenergy.vecan service. And for all devices that support the necessary can-bus commands, the Device instance can be changed. All Victron products support changing their Device instance; and most or all non-Victron products as well.
@@ Line 91: / Line 144: @@
 value = {
  'Devices/00002CC001F4/DeviceInstance': 0,
- 'Devices/00002CC001F4/FirmwareVersion': 'v2.60-beta-29',
+ 'Devices/00002CC001F4/FirmwareVersion': 'v2.73',
  'Devices/00002CC001F4/Manufacturer': 358,
  'Devices/00002CC001F4/ModelName': 'Cerbo GX',
@@ Line 123: / Line 176: @@
 </code>
-==== 5.2 New method - changing Data instance ====
+==== 6.4 New method - changing Data instance ====
 This applies only the NMEA2000-out feature. See links on top of page for what the NMEA2000 out feature is.
@@ Line 161: / Line 214: @@
 Settings/Vecan/can0/Forward/solarcharger/258/SystemInstance    0
 </code>
-==== 5.3 Old method ====
+==== 6.5 Old method ====
 (Only allows changing Device instances - not data instances as used in the NMEA2000-out function)