Service Instance Mapping

What You Will Do

In this chapter you double-click Sensor, Fusion and Actuator inside the composition HPC one after another to open the AA Internal Behavior dialog, right-click the body on the canvas and create a mapping box with Add Instance › ara::com › Service Instance. Then you pick PORT and SERVICE INSTANCE in the SERVICE INSTANCE MAPPING panel on the right. The P port of Sensor is mapped to the provider instance Provider_Sensor; the R ports of Fusion and Actuator are mapped to the consumer instances Fusion_Sensor and Actuator_Sensor. On the two consumers you enter 2 and 1 as the CLIENT ID. Sensor is shown as a procedure, Fusion shows only the part where the CLIENT ID is added, and Actuator is repeated from a table.

When you finish this chapter, Sensor.swc.io.model, Fusion.swc.io.model and Actuator.swc.io.model each hold one entry in service-instance-mappings. In ARXML Export these become the reference design's three SERVICE-INSTANCE-TO-PORT-PROTOTYPE-MAPPING elements Sensor_AA_Sensor, Fusion_AA_Sensor and Actuator_AA_Sensor.

Before You Begin

• Start from the state at the end of Executables and Processes. The five files in design/SWC/AdaptiveApplication/ have ports, executable and process, and no service-instance-mappings yet.
• The service instances created in SOME/IP Deployment and Service Instances — Provider_Sensor (provider, Instance ID 1), Fusion_Sensor and Actuator_Sensor (consumers, Required Instance ID ANY) — are in SERVICE.io.model. All three are instances of the service Sensor.
• In Binding Service Instances to the Connector you bound the three instances to the UDP ports 20003, 20002 and 20001 of the connector eth0. The read-back block of this chapter shows those endpoints as they are.
• The VALIDATION panel shows No validation issues..
• Only the three with ports — Sensor, Fusion and Actuator — are mapped. CM and EM have no ports and are not opened in this chapter.

The only things you type on the keyboard in this chapter are the two CLIENT ID values (2 and 1). Everything else is a right-click, a mouse hover, a click, a dropdown pick, Ctrl+S or Close. The name of the mapping box and the saved name are chosen by the product, not by you.

	Sensor	Fusion	Actuator
PORT	Sensor (P)	Sensor (R)	Sensor (R)
SERVICE INSTANCE	Provider_Sensor (SOME/IP)	Fusion_Sensor (SOME/IP)	Actuator_Sensor (SOME/IP)
CLIENT ID	no field	2 → 0x2	1 → 0x1
Mapping box / INSTANCE SPECIFIER	Sensor/AA/Sensor	Fusion/AA/Sensor	Actuator/AA/Sensor
PROCESS (automatic)	Sensor	Fusion	Actuator
Read-back SERVICE ID / VERSION	0x000B / 1.0	same	same
Read-back INSTANCE ID	0x0001	0xFFFF	0xFFFF
Read-back ENDPOINT	127.0.0.1:20003	127.0.0.1:20002	127.0.0.1:20001
Saved name (automatic)	Sensor_AA_Sensor	Fusion_AA_Sensor	Actuator_AA_Sensor

The three Adaptive Applications are independent of each other, so any order works. This chapter does the provider Sensor first and the consumers Fusion and Actuator afterwards.

Mapping the Port of Sensor to Provider_Sensor

Opening the AA Internal Behavior Dialog

1. In the EDITOR view on the left, click VFB under DESIGN. The tab AADesign:VFB opens with the composition node HPC [Ecu] on the root canvas. Double-click the node HPC [Ecu]. The breadcrumb changes to System > HPC, and the frame HPC shows the five nodes and two connectors created in chapter 8.

   

   Figure 10-1. The VFB editor inside the composition HPC. ① The node Sensor to double-click first, ② the node Fusion, ③ the node Actuator. Only these three have ports, and connectors run from the P of Sensor to the two R ports. CM and EM are not opened in this chapter. The node arrangement may differ from the figure depending on the result of Auto Layout in chapter 8; it has no effect on the design values.

2. Double-click the node Sensor. The dialog AA Internal Behavior [Sensor] opens. The canvas on the left shows the body of Sensor and the P port Sensor on its edge; there is no mapping box yet. The panel on the right has the PROPERTIES tab open and shows NAME Sensor, AS PROTOTYPE Sensor, DESCRIPTION - and the PORTS row P Sensor Sensor.

   

   Figure 10-2. The dialog just after opening. ① The title AA Internal Behavior [Sensor], ② the body of Sensor on the canvas, ③ the label Sensor of the P port on the right edge. There is no box inside the body yet.

Creating the Mapping Box from the Add Instance Menu

1. Right-click an empty spot of the Sensor body on the canvas. The menu shows two items, Add Port and Add Instance.

2. Hover over Add Instance. The submenu lists eleven functional clusters in this order: ara::com, ara::log, ara::sm, ara::phm, ara::nm, ara::tsync, ara::crypto, ara::idsm, ara::diag, ara::per, ara::rds.

3. Hover over ara::com. Its submenu has a single item, Service Instance.

   

   Figure 10-3. All three menu levels on one screen. ① Add Instance, ② the cluster ara::com, ③ Service Instance. Under Add Instance there are eleven clusters from ara::com to ara::rds.

4. Click Service Instance. A mapping box Sensor/AA/ appears inside the body and is selected, and the title gains a modified marker, ● AA Internal Behavior [Sensor]. The panel on the right changes to SERVICE INSTANCE MAPPING. It has four fields — INSTANCE SPECIFIER Sensor/AA/ (read-only), PROCESS Sensor (read-only), PORT (empty) and SERVICE INSTANCE (empty) — and the hint Select a port and service instance to view details below them. PORT and SERVICE INSTANCE are required: while they are empty, their labels and underlines are red, with the messages Port is required and Service Instance is required below them.

Note. The other clusters under Add Instance create the mapping boxes of their own functional clusters. This tutorial uses ara::com only. The menu always lists all eleven clusters, whatever the machine holds.

Note. The INSTANCE SPECIFIER is <Executable name>/<ROOT SWC PROTOTYPE>/<port>. In chapter 9 you left the NAME of the EXECUTABLE as Sensor and the ROOT SWC PROTOTYPE at its default AA, so it starts with Sensor/AA/, and the last segment is filled in once you pick the port. PROCESS is filled automatically with Sensor because there is only one process from chapter 9, and it cannot be changed.

Picking the PORT

1. Click the PORT field. The dropdown lists the single port of this Adaptive Application, Sensor.

   

   Figure 10-4. Right after creating the mapping box. ① The mapping box Sensor/AA/ inside the body, ② the panel title SERVICE INSTANCE MAPPING, ③ the PORT field, ④ the dropdown item Sensor. INSTANCE SPECIFIER is Sensor/AA/, PROCESS is Sensor, and SERVICE INSTANCE is empty. The labels of PORT and SERVICE INSTANCE are red, and the message Service Instance is required shows to the right of the open list.

2. Click Sensor. The mapping box changes to Sensor/AA/Sensor, INSTANCE SPECIFIER changes to Sensor/AA/Sensor, and a dashed arrow runs from the box to the P port. PORT is no longer red; SERVICE INSTANCE stays red with Service Instance is required until you pick an instance.

Caution. Pick PORT first and SERVICE INSTANCE second. The SERVICE INSTANCE dropdown offers only the instances that match the direction and the interface of the chosen port: providers only on a P port, consumers only on an R port, and only instances of the same service as the port's interface Sensor.

Picking the SERVICE INSTANCE

1. Click the SERVICE INSTANCE field. The dropdown lists a single item, Provider_Sensor (SOME/IP) — the port is a P port, so only providers pass the filter.

   

   Figure 10-5. The screen after picking the port. ① The SERVICE INSTANCE field, ② the dropdown item Provider_Sensor (SOME/IP). The box on the canvas reads Sensor/AA/Sensor and a dashed arrow runs to the P port. The SERVICE INSTANCE label is still red; the open list covers its message.

2. Click Provider_Sensor (SOME/IP). Below the fields the read-back block REFERENCED INSTANCE appears with a SOME/IP badge and four lines: SERVICE ID = 0x000B, VERSION = 1.0, INSTANCE ID = 0x0001, ENDPOINT = 127.0.0.1:20003. Under it are the table EVENTS (columns EVENT, EVENT ID, EVENTGROUP ID, TRANSPORT; row SensorData 0x0001 0x0001 UDP) and the table METHODS (columns METHOD, METHOD ID, TRANSPORT; row Calculation 0x0001 UDP). This is a provider, so there is no CLIENT ID field.

   

   Figure 10-6. The panel after picking the instance. ① The read-back block REFERENCED INSTANCE (SERVICE ID = 0x000B, VERSION = 1.0, INSTANCE ID = 0x0001, ENDPOINT = 127.0.0.1:20003), ② the table EVENTS, ③ the table METHODS. The SERVICE INSTANCE field is truncated to Provider_Sensor (SOME/… by its width, but its value is Provider_Sensor (SOME/IP). The title still reads ● AA Internal Behavior [Sensor].

Note. The read-back block is entirely read-only. 0x000B is the Service ID 11 set in chapter 6, 0x0001 is the Instance ID 1 of Provider_Sensor from chapter 6, 127.0.0.1 is the unicast address of eth0 from chapter 3, and 20003 is the UDP port bound in chapter 7. You cannot change the values here; to change them, go back to the editors of chapters 6 and 7.

Saving and Closing

1. Press Ctrl+S inside the dialog. The ● disappears from the title, which becomes AA Internal Behavior [Sensor]. The mapping box and the panel values stay visible as they are.
2. Click Close. Since you saved, the dialog closes without asking.

Note. Until you press Ctrl+S, the edit exists only in the dialog: the tab AADesign:VFB shows no modified marker ●, and the V icon in the footer gets no badge for the empty PORT and SERVICE INSTANCE. Ctrl+S inside the dialog writes service-instance-mappings into Sensor.swc.io.model and saves the AADesign:VFB tab along with it. After closing, the tab carries no modified marker ●.

Mapping the Port of Fusion to Fusion_Sensor

Fusion is a consumer. The procedure is the same as for Sensor with one addition, entering the CLIENT ID.

1. Double-click the node Fusion. AA Internal Behavior [Fusion] opens, and the canvas shows the body of Fusion with the R port Sensor on its edge. The PORTS row reads R Sensor Sensor.

2. Right-click the body and click Add Instance › ara::com › Service Instance. The box Fusion/AA/ appears and PROCESS is Fusion. As for Sensor, the empty PORT and SERVICE INSTANCE are red.

3. Click the PORT field and pick Sensor. The box becomes Fusion/AA/Sensor.

4. Click the SERVICE INSTANCE field. The dropdown lists two items, Actuator_Sensor (SOME/IP) and Fusion_Sensor (SOME/IP) — the port is an R port, so only the two consumers pass the filter. Click Fusion_Sensor (SOME/IP).

5. Check the read-back block: SERVICE ID = 0x000B, VERSION = 1.0, INSTANCE ID = 0xFFFF, ENDPOINT = 127.0.0.1:20002. The EVENTS and METHODS tables are the same as for Sensor. Between the METHODS header and its table there is a CLIENT ID field with a DEC / HEX toggle to the right of its label; the default is HEX and the field is empty.

6. Type 2 into the CLIENT ID field and press Tab. The field shows 0x2.

   

   Figure 10-7. The Fusion dialog after entering the CLIENT ID. ① The SERVICE INSTANCE field Fusion_Sensor (SOME/IP), ② the read-back line INSTANCE ID = 0xFFFF, ③ the read-back line ENDPOINT = 127.0.0.1:20002, ④ the CLIENT ID field (0x2, with HEX active on the DEC / HEX toggle). The box Fusion/AA/Sensor on the canvas is joined to the R port on the left edge by a dashed line, and its left end touches the port icon. The title reads ● AA Internal Behavior [Fusion].

7. Press Ctrl+S, then click Close.

Note. You can type the CLIENT ID without the 0x prefix. HEX is the default, so typing 2 shows 0x2 and the file stores 2. The reference values 1 and 2 are the same in decimal and hexadecimal, so there is no need to switch the toggle. The consumers' INSTANCE ID = 0xFFFF comes from leaving the Required Instance ID at ANY in chapter 6; the model value is 65535.

Mapping the Port of Actuator to Actuator_Sensor

Map Actuator the same way. Double-click the node, right-click the body and click Add Instance › ara::com › Service Instance, pick and enter the values from the table, then finish with Ctrl+S and Close.

Node	PORT	SERVICE INSTANCE	CLIENT ID	Read-back INSTANCE ID / ENDPOINT
Actuator	Sensor	Actuator_Sensor (SOME/IP)	1 → 0x1	0xFFFF / 127.0.0.1:20001

The SERVICE INSTANCE dropdown shows the same two items as for Fusion, Actuator_Sensor (SOME/IP) and Fusion_Sensor (SOME/IP). Here you pick Actuator_Sensor (SOME/IP).

Figure 10-8. The Actuator dialog after saving with Ctrl+S. ① The title AA Internal Behavior [Actuator] (no modified marker), ② the mapping box Actuator/AA/Sensor, ③ the CLIENT ID field 0x1. The SERVICE INSTANCE field is truncated to Actuator_Sensor (SOME/…, and the read-back block reads INSTANCE ID = 0xFFFF, ENDPOINT = 127.0.0.1:20001. The box and the panel values stay visible after saving.

Caution. The dropdown items are the same on Fusion and Actuator. Confirm from the ENDPOINT of the read-back block that you picked Fusion_Sensor (SOME/IP) on Fusion and Actuator_Sensor (SOME/IP) on Actuator: Fusion must read 127.0.0.1:20002 and Actuator must read 127.0.0.1:20001.

Once all three dialogs are closed, the HPC canvas looks unchanged. Mapping boxes are visible only inside the dialog.

Figure 10-9. The HPC canvas after the mapping. ① Sensor, ② Fusion, ③ Actuator. Actuator, the last one opened, is still selected and highlighted, and the tab AADesign:VFB carries no modified marker ●.

Each of the three files gains one service-instance-mappings entry. The entry of Sensor.swc.io.model is:

"service-instance-mappings": [
  {
    "name": "Sensor_AA_Sensor",
    "port-ref": "Sensor",
    "service-instance-ref": "Provider_Sensor",
    "instance-type": "someip",
    "process-ref": "Sensor",
    "position": { "x": 0, "y": 48 },
    "size": { "width": 160, "height": 32 }
  }
]

In Fusion.swc.io.model the name is Fusion_AA_Sensor, the service-instance-ref is Fusion_Sensor, the process-ref is Fusion, and there is an additional client-id 2. In Actuator.swc.io.model they are Actuator_AA_Sensor, Actuator_Sensor and Actuator with client-id 1. The entry of the provider Sensor has no client-id key at all. The product builds name as <Executable>_<ROOT SWC PROTOTYPE>_<port>, and position and size are the coordinates of the box. CM.swc.io.model, EM.swc.io.model, SERVICE.io.model and IVC.io.model are unchanged. VFB.io.model is written again when you save a dialog, but only the modified time stamp in its metadata changes.

Viewing the Validation Result

1. Look at the V icon in the footer at the bottom of the window, the fifth icon from the left. It carries no badge.

2. Look at the VALIDATION panel. If it is closed, click the V icon in the footer. The header carries no badge, and under the column headers ELEMENT TYPE, NAME, DESCRIPTION and CONSTR the body reads No validation issues..

   

   Figure 10-10. The VALIDATION panel after saving all three dialogs. The body reads No validation issues..

Note. This chapter saves only after both PORT and SERVICE INSTANCE are picked. What validation reports when you save with one of them empty was not checked in this chapter.

Why Is It Designed This Way?

• Only the three with ports are mapped. The reference design has three SERVICE-INSTANCE-TO-PORT-PROTOTYPE-MAPPING elements, one under the Manifest of each of Sensor, Fusion and Actuator. CM and EM have neither ports nor mappings.
• The CLIENT ID is absent on the provider and 2, 1 on the consumers. In the reference design the CLIENT-ID under PARA-SOMEIP-CONFIGURATION is empty for Sensor, 2 for Fusion and 1 for Actuator. PAIO shows no CLIENT ID field on a provider mapping, so the export carries an empty CLIENT-ID, and the values entered on the consumers are exported as they are.
• The name is <Executable>_<ROOT SWC PROTOTYPE>_<port>. The three reference names Sensor_AA_Sensor, Fusion_AA_Sensor and Actuator_AA_Sensor follow this rule, and they are reproduced exactly because chapter 9 left the ROOT SWC PROTOTYPE at its default AA. In the reference design only CM and EM use RootSwComponent; those two have no mappings, so this does not affect any mapping name.
• The exported Sensor_AA_Sensor block differs from the reference design in one line only. That line is the CONTEXT-ROOT-SW-COMPONENT-PROTOTYPE-REF of the PORT-PROTOTYPE-IREF. The export has /Executable/Sensor/Sensor/AA, which points at the root prototype AA of the Executable Sensor, while the reference design has /Executable/Sensor/AA, one level short, which names no element. The details are in ARXML Export.
• The read-back block only shows the results of chapters 6 and 7. SERVICE ID, INSTANCE ID and ENDPOINT are not entered in this dialog. The mapping decides only which port uses which instance.

Checklist

• Double-clicking Sensor, Fusion and Actuator shows one mapping box inside each body — Sensor/AA/Sensor, Fusion/AA/Sensor, Actuator/AA/Sensor — with a dashed arrow between the box and the port.
• Clicking the box shows the panel SERVICE INSTANCE MAPPING with PORT Sensor and SERVICE INSTANCE Provider_Sensor (SOME/IP), Fusion_Sensor (SOME/IP) and Actuator_Sensor (SOME/IP) respectively.
• The read-back ENDPOINT is 127.0.0.1:20003 for Sensor, 127.0.0.1:20002 for Fusion and 127.0.0.1:20001 for Actuator, and the INSTANCE ID is 0x0001 for Sensor and 0xFFFF for the other two.
• The CLIENT ID of Fusion is 0x2, that of Actuator is 0x1, and Sensor has no CLIENT ID field.
• Neither the dialog title nor the tab AADesign:VFB carries a modified marker ●.
• CM and EM were not opened and their files are unchanged.
• The VALIDATION panel shows No validation issues. and the header carries no badge.

Next Step

In Logging and DLT you enter the Application ID and the DLT contexts in the LOG CONFIG of the five processes.