---
alias: user-guide-oib-extensions-maintenance
tags:
- connect iot
description: "This documentation details settings and events for a maintenance system, facilitating data updates and notifications"
---
# Maintenance
### Communication Settings
| Name | Type | Possible Values | Default Value | Description |
| ---------------------- | ------- | ------------------------------------------------ | -------------------------- | ------------------------------------------------------------ |
| enableMode | Enum | `None`
`OnePerEnterprise`
`OnePerSite` | `None` | How should activate Maintenance instance:
`None` - No instance will be used
`OnePerEnterprise` - One Instance for all Lines (Enterprise level)
`OnePerSite` - One Instance for all Lines (Site level) |
| callbackPort | Integer | | 0 | What port to use to receive events from Maintenance. Use `0` to use a free port starting at `callbackBasePort` + 300 |
| subscriptionNameSuffix | String | | | Will be added to the subscription name. Possible replacement tokens are `${id}` and `${guid}` |
| subscriptionExpiration | Integer | | 4 | Number of hours to subscribe for maintenance events. Will renew every 30 minutes the same amount of time defined. |
| eventsExpiration | Integer | | 60 | Expiration time (seconds) between events triggered and received. Used to avoid processing old Maintenance events that occurred while driver was not communicating with OIB |
| subscriptionMode | Enum | `Permanent` | `Permanent` `NonPermanent` | Define the way the subscription is registered.`Permanent` for `PushWithAck`, `NonPermanent` for `PushReliable` |
| bulkEventCountSize | Integer | | 1000 | Bulk Event Count Size: when reached will trigger the bulk event |
### Properties
#### Maintenance.Property.DoPeriodicUpdate
| Property Id | Data Type | Possible Values | Description |
| ----------------------------------------------------------------------------------------------------------------- | --------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Maintenance.Property.DoPeriodicUpdate | Boolean | | When enabled (default is disabled), allows parsing of the `NewMaintenanceData`. If disabled (default) will not send a new MaintenanceDataResponse, so OIB Eventing will store (and retry) the message later on. |
| This is useful to do not consume maintenance eventing messages until we are ready (e.g.: factory layout is ready) | | | |
### Events
Maintenance is used to fetch and also receive maintenance related events.
These event are triggered on changes on the `ASM:OIB:MaintenanceData:Notify` `eventing` topic.
#### Maintenance.Event.TapeFeeders
This event is triggered every time a NewMaintenanceData is received with updated SetupConfiguration (contains the TapeFeeders).
This event must contain at least one `feeders` object on the Equipment Configuration and Setup Configuration Object
This event contains the following property:
| Property Id | Data Type | Possible Values | Description |
| -------------------------------- | --------- | --------------- | --------------------------------------------------------------------- |
| Maintenance.Property.TapeFeeders | Object | | Structure of a Equipment Configuration and Setup Configuration Object |
Structure of the Equipment Configuration and Setup Configuration object
| Object key name | Data Type | Possible Values | Description |
| --------------- | --------- | --------------- | -------------------------------------------------------------------------------------------------------------------------- |
| lines | Object | | Line structure |
| stations | Object | | Station structure |
| heads | Object | | PlaceHeads structure (see `Maintenance.Event.PlaceHeads`) (optional on Maintenance.Event.TapeFeeders event) |
| tapeFeeders | Object | | TapeFeeders structure |
| nozzlesInGarage | Object | | NozzlesInGarage structure (see `Maintenance.Event.NozzlesInGarage`) (not available on Maintenance.Event.TapeFeeders event) |
The `tapeFeeders` object structure is:
| Object key name | Data Type | Possible Values | Description |
| --------------- | --------- | --------------- | --------------------------------------------------------------------------------------------------- |
| feederId | String | | Unique id of the tape feeder |
| feederType | String | | Feeder Type Name |
| feederTypeId | Double | | Feeder type (should relate to the `TapeFeederType` exposed on `OIB.Property.FeederTypes` property ) |
| location | String | | Location of the Feeder |
| name | String | | Feeder Name |
#### Maintenance.Event.PlaceHeads
This event is triggered every time a NewMaintenanceData is received with updated EquipmentConfiguration (contains the PlaceHeads).
This event contains the structure described in the `Maintenance.Event.TapeFeeders` event with at least one `heads` object on the Equipment Configuration and Setup Configuration Object.
The `heads` structure is:
| Object key name | Data Type | Possible Values | Description |
| --------------- | --------- | --------------- | --------------------------------------------------------------------------------------------------- |
| id | String | | Unique id of the place head |
| name | String | | Place head name |
| type | String | | Place head type (should relate to the `HeadType` exposed on `OIB.Property.FactoryLayout` property ) |
| typeId | Integer | | Place head type Id (useful to relate with specific Maintenance Order Activities) |
| location | String | | Location of the head |
Example of a `Maintenance.Event.TapeFeeders` or `Maintenance.Event.PlaceHeads` event structure:
```json
{
"lines": [
{
"fullPath": "TC-ROOM\\TX2_00012805_Line",
"name": "TX2_00012805_Line",
"stations": [
{
"fullPath": "TC-ROOM\\TX2_00012805_Station",
"name": "TX2_00012805_Station",
"serialNumber": "00012805",
"heads": [
{
"id": "03053528-05 KL -E3-0004",
"name": "CPP_2",
"type": "CPP",
"typeId": 8,
"location": "1.2.1",
},
{
"id": "00000000-00 KL -H4-006300000000-00 KL -H4-0043",
"name": "TWIN_1",
"type": "TWIN",
"typeId": 10,
"location": "1.1.1",
}
],
"tapeFeeders": [
{
"feederId": "08FAUT901252",
"feederType": "8mm-X Tape",
"feederTypeId": 264,
"location": "2.4",
"name": "8mm-X Tape_2.4",
},
{
"feederId": "24KL-H300019",
"feederType": "24mm-X Tape",
"feederTypeId": 280,
"location": "2.6",
"name": "24mm-X Tape_2.6"
}
]
}
]
},
{
"fullPath": "TC-ROOM\\SXV3-Eric-L",
"name": "SXV3-Eric-L",
"stations": [
{
"fullPath": "TC-ROOM\\SXV3-Eric",
"name": "SXV3-Eric",
"serialNumber": "20006270",
"heads": [
{
"id": "03126608-05 KL -M1-0034",
"name": "C&P20-P2_1",
"type": "C&P20-P2",
"location": "1.1.1"
},
{
"id": "03126608-05 KL -M1-0031",
"name": "C&P20-P2_2",
"type": "C&P20-P2",
"location": "1.2.1"
}
],
"tapeFeeders": [
{
"feederId": "08ATML701618",
"feederType": "8mm-X Tape",
"feederTypeId": 264,
"location": "2.31",
"name": "8mm-X Tape_2.31"
}
]
}
]
},
{
"fullPath": "TCM\\X4S_DT",
"name": "X4S_DT",
"stations": [
{
"fullPath": "TCM\\X4S",
"name": "X4S",
"serialNumber": "00010401",
"heads": [
{
"id": "00000000-00 KL -E2-003200000000-00 KL -E2-0031",
"name": "TWIN_3",
"type": "TWIN",
"location": "2.3.1"
}
],
"tapeFeeders": [
{
"feederId": "08FAUT200033",
"feederType": "8mm-X Tape",
"feederTypeId": 264,
"location": "2.33",
"name": "8mm-X Tape_2.33",
}
]
}
]
}
]
}
```
#### Maintenance.Event.NozzlesInGarage
This event is triggered every time a NewMaintenanceData is received with updated EquipmentConfiguration (contains the NozzlesInGarage).
This event contains the structure described in the `Maintenance.Event.TapeFeeders` event with at least one `heads` object and one `nozzlesInGarage` object on the Equipment Configuration and Setup Configuration Object.
The `nozzlesInGarage` structure is:
| Object key name | Data Type | Possible Values | Description |
| --------------- | --------- | --------------- | ----------------------------------------------------------------------------------------------- |
| nozzleId | String | | Unique id of the nozzle |
| nozzleType | String | | Nozzle Type Name |
| nozzleTypeId | Double | | Nozzle type (should relate to the `NozzleType` exposed on `OIB.Property.NozzleTypes` property ) |
| location | String | | Location of the Nozzle |
| name | String | | Nozzle Name |
Example of a `Maintenance.Event.NozzlesInGarage` event structure:
```json
{
"lines": [
{
"fullPath": "TCM\\TX2_DT",
"name": "TX2_DT",
"stations": [
{
"fullPath": "TCM\\TX2",
"name": "TX2",
"serialNumber": "00012805",
"heads": [
{
"id": "03053528-05 KL -E3-0004",
"name": "CPP_2",
"type": "CPP",
"typeId": 12,
"location": "1.2.1",
"$id": "8"
},
{
"id": "00000000-00 KL -H4-0063",
"name": "TWIN_1_Module_1",
"type": "TWIN",
"typeId": 4,
"location": "1.1.1.1",
"$id": "9"
},
{
"id": "00000000-00 KL -H4-0043",
"name": "TWIN_1_Module_2",
"type": "TWIN",
"typeId": 4,
"location": "1.1.1.2",
"$id": "10"
}
],
"nozzlesInGarage": [
{
"nozzleId": "00012805_10015",
"nozzleType": "2004",
"nozzleTypeId": 2004,
"location": "2.1.1.10",
"name": "00012805_NozzleChanger_1_L_1_1_1_10_2004",
"$id": "11"
},
{
"nozzleId": "00012805_10238",
"nozzleType": "2004",
"nozzleTypeId": 2004,
"location": "2.1.1.1",
"name": "00012805_NozzleChanger_1_L_1_1_1_1_2004",
"$id": "37"
},
{
"nozzleId": "00012805_10274",
"nozzleType": "2038",
"nozzleTypeId": 2038,
"location": "2.1.3.7",
"name": "00012805_NozzleChanger_1_L_1_1_3_7_2038",
"$id": "49"
},
{
"nozzleId": "00012805_10305",
"nozzleType": "2057",
"nozzleTypeId": 2057,
"location": "2.1.4.12",
"name": "00012805_NozzleChanger_1_L_1_1_4_12_2057",
"$id": "80"
}
]
}
]
}
]
}
```
#### Maintenance.Event.DPAxis
This event is triggered every time a NewMaintenanceData is received with updated EquipmentConfiguration (contains the DPAxis).
This event contains the following structure:
The `Maintenance.Property.DPAxis` structure is:
| Object key name | Data Type | Possible Values | Description |
| --------------------- | --------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| id | String | | Unique id of the place head |
| headId | String | | Place head unique id (should relate to the `id` exposed on `OIB.Property.PlaceHeads` property ) |
| name | String | | DPAxis name |
| location | String | | Location of the DPAxis |
| headSegmentActivation | Int32 | | Status of the Head Segment (possible values:`SegmentEnabled=0`, `SegmentNotMounted=1`, `SegmentNotUsed=2`, `DisabledByUser=3`, `DisabledByHardwareAxisWarmup=4`, `DisabledByHardwareAxisMovementError=5`, `DisabledByHardwareValveClosed=6` and `Unknown=7`) |
| lineFullPath | String | | Line FullPath |
| stationMachineId | String | | Station Machine Id |
Example of a `Maintenance.Event.DPAxis`event structure:
```json
[
{
"id": "10000000-00 000-H1-DP1_",
"headId": "00000000-00 000-H1-_____",
"name": "C&P20_1_DpAxis1",
"location": "1.1.1.1",
"headSegmentActivation": "0",
"lineFullPath": "Virtual Lines\\Virtual Line 01",
"stationMachineId": "10000000",
}
]
```
#### Maintenance.Event.DPAxisOffset
Same as `Maintenance.Property.DPAxisOffset`, but will only send a delta of new changes to the DPAxis, where as DPAxis is a snapshot of the information.
#### Maintenance.Event.ServiceAndMaintenanceData
This event is triggered on changes on the `ASM:OIB:MaintenanceData:Notify` `eventing` topic and contains the agregated data received.
This event contains the following property:
| Property Id | Data Type | Possible Values | Description |
| ---------------------------------------------- | --------- | --------------- | ------------------------------------------------- |
| Maintenance.Property.ServiceAndMaintenanceData | Object | | Structure of a Service And MaintenanceData Object |
This event uses the structure detailed in `OibEventOccurrence` section with an `Maintenance.Property.ServiceAndMaintenanceData` as an array of MaintenanceData occurrences (detailed below). Example:
```json
{
"messageId": "e11382dea7494868b183c4d22411083e",
"eventId": "Maintenance.Event.ServiceAndMaintenanceData",
"timestamp": "2020-04-28T09:01:13.820Z",
"values": {
"Maintenance.Property.ServiceAndMaintenanceData": [
{
"EventType": "CalibrationData",
"UniqueId": "10000000_Gantry_X_2_L_1",
"EventName": "SystemIdentification",
"...": "..."
}
{
"EventType": "VerificationData",
"UniqueId": "10000000-00 000-H4-DP15",
"EventName": "TotalDisabledDPs",
"...": "..."
}
]
```
Maintenance Data can be:
- CalibrationDetails: All latest calibration information about this equipment item.
- ErrorDetails: All errors signaled by this equipment item.
- MaintenanceDetails: All latest maintenance results about this equipment item.
- SensorDetails: All latest sensor samples from this equipment item.
- VerificationDetails All latest verification results about this equipment item.
These occurrences have a structure detailed in the following section.
#### Maintenance Event Occurrence Details
| Object key name | Data Type | Possible Values | Description |
| --------------- | --------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| EventType | String | `VerificationData
``CalibrationData
``MaintenanceData
``SensorData
``ErrorData` | Event type of the event received |
| UniqueId | String | | Which equipment item this data is about. You can match this property with the UniqueId property of the EquipmentConfigurationData and SetupConfigurationData to see what that is together with the MachineId property of the StationServiceAndMaintenanceData that is exposed by the `FactoryLayout` property and `PlaceHeads` and `TapeFeeders` events. |
| Line | Object | | Line where the event occurred |
| Station | Object | | Station where the event occurred |
| EventName | String | | Event Name - An event identifier that is known to MES logic, detailed in the correspondent section |
| EventValue | | | Event Value has different types according to `EventType`. These are detailed in the correspondent section |
| TimeStamp | DateTime | | Date time of the `eventValue` |
| ExtraData | Object | | Object as received from OIB interface mainly used as a extra information data source |
##### VerificationDetails
Contains all latest verification results about this equipment item.
Exposes the following EventNames with EventValues:
| EventName | EventValue Type |
| ----------------------------------- | ---------------------- |
| `DisabledDPsDueToNozzleMaintenance` | Double |
| `DisabledDPsDueToErrors` | Double |
| `TotalDisabledDPs` | Double |
| `ACTCmkResultX` | Double |
| `ACTCmkResultY` | Double |
| `CameraLightingFCCS` | String (`OK` or `NOK`) |
| `VacuumPressureOpen` | String (`OK` or `NOK`) |
| `VacuumPressureClosed` | String (`OK` or `NOK`) |
| `VacuumPressureNozzleClosed` | String (`OK` or `NOK`) |
| `NozzleLengthSensor` | String (`OK` or `NOK`) |
| `NozzleLengthZAxis` | String (`OK` or `NOK`) |
| `NozzleScanX` | String (`OK` or `NOK`) |
| `NozzleScanY` | String (`OK` or `NOK`) |
| `NozzleScanPhi` | String (`OK` or `NOK`) |
| `ComponentSensor` | String (`OK` or `NOK`) |
Example of a VerificationData occurrence:
```json
{
"EventType": "VerificationData",
"UniqueId": "10000000-00 000-H1-DP6_",
"Line": {
"name": "Virtual Line 01",
"fullPath": "Virtual Lines\\Virtual Line 01",
},
"Station": {
"name": "Virtual SX4 01",
"fullPath": "Virtual Stations\\Virtual SX4 01",
"model": "",
"serialNumber": "10000000",
"stationType": "PickAndPlace",
"ipAddress": null,
},
"EventName": "DisabledDPsDueToErrors",
"EventValue": 0,
"Timestamp": "1753-01-01T00:36:45.000Z",
"ExtraData": {},
},
```
##### CalibrationDetails
Contains all latest calibration information about this equipment item.
Exposes the following EventNames with EventValues:
| EventName | EventValue Type |
| ----------------------- | ---------------------- |
| `TravelRange` | String (`OK` or `NOK`) |
| `X-AxisParametrization` | String (`OK` or `NOK`) |
| `SystemIdentification` | String (`OK` or `NOK`) |
| `ZeroPointOffset` | String (`OK` or `NOK`) |
| `BoardCamera` | String (`OK` or `NOK`) |
| `FeedUnits` | String (`OK` or `NOK`) |
| `NozzleChanger` | String (`OK` or `NOK`) |
| `BoardReferenceCorner` | String (`OK` or `NOK`) |
| `ComponentCamera` | String (`OK` or `NOK`) |
| `SegmentOffset` | String (`OK` or `NOK`) |
| `ComponentSensor` | String (`OK` or `NOK`) |
| `ZeroPressure` | String (`OK` or `NOK`) |
| `BoardMapping` | String (`OK` or `NOK`) |
| `HeadMapping` | String (`OK` or `NOK`) |
| `HeadAndCameras` | String (`OK` or `NOK`) |
| `VacuumTooling` | String (`OK` or `NOK`) |
Example of a CalibrationData occurrence:
```json
{
"EventType": "CalibrationData",
"UniqueId": "10000000_Gantry_X_2_L_1",
"Line": {
"name": "Virtual Line 01",
"fullPath": "Virtual Lines\\Virtual Line 01"
},
"Station": {
"name": "Virtual SX4 01",
"fullPath": "Virtual Stations\\Virtual SX4 01",
"model": "",
"serialNumber": "10000000",
"stationType": "PickAndPlace",
"ipAddress": null
},
"EventName": "SystemIdentification",
"EventValue": "NOK",
"Timestamp": "1753-01-01T00:36:45.000Z",
"ExtraData": {}
},
```
##### MaintenanceDetails
Exposes the following EventNames with EventValues:
| EventName | EventValue Type |
| ------------------ | --------------- |
| `FeederCycleCount` | String |
Example of a MaintenanceData occurrence:
```json
{
"EventType": "MaintenanceData",
"UniqueId": "08FAUB900458",
"Line": {
"name": "Virtual Line 01",
"fullPath": "Virtual Lines\\Virtual Line 01",
},
"Station": {
"name": "Virtual SX4 01",
"fullPath": "Virtual Stations\\Virtual SX4 01",
"model": "",
"serialNumber": "10000000",
"stationType": "PickAndPlace",
"ipAddress": null,
},
"EventName": "FeederCycleCount",
"EventValue": "1700466",
"Timestamp": "2020-04-22T16:19:56",
"ExtraData": {},
},
```
##### SensorDetails
Exposes the following EventNames with EventValues:
| EventName | EventValue Type |
| --------------------------------- | --------------- |
| `SMPSInput` | Double |
| `SMPSOutput160V` | Double |
| `SMPSOutput300V` | Double |
| `SMPSTemperature` | Double |
| `CP20xDPTemperature1` | Double |
| `TemperatureHeadInterfaceAdapter` | Double |
| `TemperatureGantry` | Double |
| `FCUInputVoltageLocation` | Double |
Example of an SensorData occurrence:
```json
{
"EventType": "SensorData",
"UniqueId": "00000000-00 000-H1-_____",
"Line": {
"name": "Virtual Line 01",
"fullPath": "Virtual Lines\\Virtual Line 01"
},
"Station": {
"name": "Virtual SX4 01",
"fullPath": "Virtual Stations\\Virtual SX4 01",
"model": "",
"serialNumber": "10000000",
"stationType": "PickAndPlace",
"ipAddress": null
},
"EventName": "TemperatureHeadInterfaceAdapter",
"EventValue": 16,
"Timestamp": "2020-04-28T09:00:55.000Z",
"ExtraData": {}
},
```
##### ErrorDetails
Exposes the following EventNames with EventValues:
| EventName | EventValue Type |
| ------------------------------------------------------------------------------- | --------------- |
| `CountingErrorsYAxis` | Double |
| `TransportErrorsMachineHasStopped-CannotSetConveyorLaneWidth` | Double |
| `TransportErrorsMachineHasStopped-CannotSetStandardWidth` | Double |
| `TransportErrorsMachineHasStopped-AConveyorErrorHasOccurred` | Double |
| `TransportErrorsMachineHasStopped-CannotMeasureFiducialOnConveyorRail` | Double |
| `TransportErrorsMachineHasStopped-BoardHasNotArrivedTargetSection` | Double |
| `TransportErrorsMachineHasStopped-BoardHasNotArrived` | Double |
| `TransportErrorsMachineHasStopped-CannotMoveBoardTargetSectionTargetStopper` | Double |
| `TransportErrorsMachineHasStopped-CannotMoveBoardOutOfMachine` | Double |
| `TransportErrorsMachineHasStopped-CannotMoveAllBoardsOutOfTheMachine` | Double |
| `TransportErrorsMachineHasStopped-CannotLockInputSection` | Double |
| `TransportErrorsMachineHasStopped-ConveyorLaneAlreadyOccupiedPleaseRemoveBoard` | Double |
| `TransportErrorsMachineHasStopped-CannotFindBoardInConveyorLanePleaseLoadBoard` | Double |
| `TransportErrorsMachineHasStopped-CannotReferenceConveyor` | Double |
| `TransportErrorsMachineHasStopped-LiftingTableError` | Double |
| `XFeederFoilTorn` | Double |
| `XFeederFoilJam` | Double |
### Commands
#### Maintenance.Command.TriggerServiceAndMaintenanceData
This command will use the `MaintenanceDataService` service from `SIPLACE.Monitoring` to execute a `GetServiceAndMaintenanceData` request.
The actual data response will be exposed by the `Maintenance.Event.EquipmentCenterEvent` event that will be triggered.
This command can have the following parameters:
| Command Name | Type | Mandatory | Possible Values | Default Value | Description |
| ------------ | ------ | --------- | --------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| LineName | String | No | | | Contains SiPlacePro line names for which the maintenance data is queried for (comma separated). If empty will query all lines. |
Example:
SendRequest `connect.iot.driver.oib.executeCommand`
```json
{
"commandId": "Maintenance.Command.TriggerServiceAndMaintenanceData",
"parameters": {
"LineName": "Virtual Line 01"
}
}
```
#### Maintenance.Command.TriggerServiceAndMaintenanceData
This command will use the `MaintenanceDataService` service from `SIPLACE.Monitoring` to execute a `GetServiceAndMaintenanceData` request.
The actual data response will be exposed by the `Maintenance.Event.ServiceAndMaintenanceData` event that will be triggered.
This command can have the following parameters:
| Command Name | Type | Mandatory | Possible Values | Default Value | Description |
| ------------ | ------ | --------- | --------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| LineName | String | No | | | Contains SiPlacePro line names for which the maintenance data is queried for (comma separated). If empty will query all lines. |
Example:
SendRequest `connect.iot.driver.oib.executeCommand`
```json
{
"commandId": "Maintenance.Command.TriggerServiceAndMaintenanceData",
"parameters": {
"LineName": "Virtual Line 01"
}
}
```
#### Maintenance.Command.TriggerEquipmentAndSetupConfiguration
This command will use the `MaintenanceDataService` service from `SIPLACE.Monitoring` to execute a `GetEquipmentConfiguration` and `GetSetupConfiguration` request.
The actual data response will be exposed by the `Maintenance.Event.PlaceHeads`, `Maintenance.Event.TapeFeeders`, `Maintenance.Event.DPAxis` and `Maintenance.Event.DPAxisOffset` event that will be triggered.
This command can have the following parameters:
| Command Name | Type | Mandatory | Possible Values | Default Value | Description |
| ------------ | ------ | --------- | --------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| LineName | String | No | | | Contains SiPlacePro line names for which the maintenance data is queried for (comma separated). If empty will query all lines. |
Example:
SendRequest `connect.iot.driver.oib.executeCommand`
```json
{
"commandId": "Maintenance.Command.TriggerEquipmentAndSetupConfiguration",
"parameters": {
"LineName": "Virtual Line 01"
}
}
```