openapi: 3.0.0
info:
  description: The API for Profile management in the ThingPark X Platform
  version: 2.3.0
  title: Thingpark X Profile management Module API
externalDocs:
  description: For more information, please check the online examples in this documentation.
  url: '/location-profile-management/latest/doc/index.html'
tags:
  - name: Profile
    description: Profile operations are used to configure configuration profiles for setting batch parameters on Abeeway trackers. Currently only Abeeway Asset Tracker devices are supported.
  - name: Parameter
    description: Parameter operations are used to retrieve firmware specific parameters
  - name: Test Pattern
    description: Test pattern operations are used to retrieve test patterns used for firmware testing
paths:
  /profiles:
    get:
      parameters:
        - description: Optional customer ID only required when called with an administrator account.
          in: query
          name: customerId
          required: false
          schema:
            type: string
        - name: profileId
          in: query
          description: Optional profile ID only required when called with an administrator account.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Profiles retrieved successfully.
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Profile'
                type: array
        '400':
          description: Any error when processing the request
        '401':
          description: Unauthorized - invalid api key or user not authorized for access
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
      tags:
        - Profile
      description: Retrieves a list of profiles existing within authorized scopes.
      summary: Profile retrieval
      x-since-version: 1.0.0
    post:
      parameters:
        - description: Optional customer ID only required when called with an administrator account.
          in: query
          name: customerId
          required: false
          schema:
            type: string
        - name: profileId
          in: query
          description: Optional profile ID only required when called with an administrator account.
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Profile'
          application/xml:
            schema:
              $ref: '#/components/schemas/Profile'
        description: Contents of the Profile to create.
        required: true
      responses:
        '201':
          description: Profile created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Profile'
        '400':
          description: Any error when processing the request
        '401':
          description: Unauthorized - invalid api key or user not authorized for access
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
      tags:
        - Profile
      description: Creates a new profile.
      summary: Profile creation
      x-since-version: 1.0.0
  /profiles/{namespace}:
    get:
      parameters:
        - description: Namespace of the profile to retrieve.
          in: path
          name: namespace
          required: true
          schema:
            type: string
        - description: Optional customer ID only required when called with an administrator account.
          in: query
          name: customerId
          required: false
          schema:
            type: string
        - name: profileId
          in: query
          description: Optional profile ID only required when called with an administrator account.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Profiles retrieved successfully.
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Profile'
                type: array
        '400':
          description: Any error when processing the request
        '401':
          description: Unauthorized - invalid api key or user not authorized for access
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
      tags:
        - Profile
      description: Retrieves the profiles corresponding to the provided profile namespace
      summary: Profile retrieval in the given namespace
      x-since-version: 1.0.0
  /profiles/{namespace}/{name}:
    delete:
      parameters:
        - description: Namespace of the profile to delete.
          in: path
          name: namespace
          required: true
          schema:
            type: string
        - description: Name of the profile to delete.
          in: path
          name: name
          required: true
          schema:
            type: string
        - description: Optional customer ID only required when called with an administrator account.
          in: query
          name: customerId
          required: false
          schema:
            type: string
        - name: profileId
          in: query
          description: Optional profile ID only required when called with an administrator account.
          required: false
          schema:
            type: string
      responses:
        '204':
          description: Profile deleted successfully.
          content: {}
        '400':
          description: Any error when processing the request
        '401':
          description: Unauthorized - invalid api key or user not authorized for access
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
      tags:
        - Profile
      description: Deletes the profile corresponding to the provided profile name
      summary: Profile deletion
      x-since-version: 1.0.0
    get:
      parameters:
        - description: Namespace of the profile to retrieve.
          in: path
          name: namespace
          required: true
          schema:
            type: string
        - description: Name of the profile to retrieve.
          in: path
          name: name
          required: true
          schema:
            type: string
        - description: Optional customer ID only required when called with an administrator account.
          in: query
          name: customerId
          required: false
          schema:
            type: string
        - name: profileId
          in: query
          description: Optional profile ID only required when called with an administrator account.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Profile retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Profile'
        '400':
          description: Any error when processing the request
        '401':
          description: Unauthorized - invalid api key or user not authorized for access
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
      tags:
        - Profile
      description: Retrieves the profile corresponding to the provided profile name
      summary: Profile retrieval
      x-since-version: 1.0.0
    put:
      parameters:
        - description: Namespace of the profile to delete.
          in: path
          name: namespace
          required: true
          schema:
            type: string
        - description: Name of the profile to update.
          in: path
          name: name
          required: true
          schema:
            type: string
        - description: Optional customer ID only required when called with an administrator account.
          in: query
          name: customerId
          required: false
          schema:
            type: string
        - name: profileId
          in: query
          description: Optional profile ID only required when called with an administrator account.
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Profile'
          application/xml:
            schema:
              $ref: '#/components/schemas/Profile'
        description: Contents of the profile to update.
        required: true
      responses:
        '200':
          description: Profile updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Profile'
        '400':
          description: Any error when processing the request
        '401':
          description: Unauthorized - invalid api key or user not authorized for access
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
      tags:
        - Profile
      description: Updates the Profile corresponding to the provided profile name, if that profile is within authorized scopes.
      summary: Profile update
      x-since-version: 1.0.0
  /computedProfiles/{namespace}/{name}:
    get:
      parameters:
        - description: Namespace of the profile to retrieve.
          in: path
          name: namespace
          required: true
          schema:
            type: string
        - description: Name of the profile to retrieve.
          in: path
          name: name
          required: true
          schema:
            type: string
        - description: Optional customer ID only required when called with an administrator account.
          in: query
          name: customerId
          required: false
          schema:
            type: string
        - name: profileId
          in: query
          description: Optional profile ID only required when called with an administrator account.
          required: false
          schema:
            type: string
        - description: Tracker device EUI.
          in: query
          name: deviceEUI
          required: true
          schema:
            type: string
        - description: MCU firmware version.
          in: query
          name: firmwareVersion
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Profile computed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputedProfile'
        '400':
          description: Any error when processing the request
        '401':
          description: Unauthorized - invalid api key or user not authorized for access
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
      tags:
        - Profile
      description: Retrieves the profile corresponding to the provided profile name
      summary: Profile retrieval
      x-since-version: 1.0.0
  /parameters:
    get:
      parameters:
        - name: tpxProtocolIdentifier
          in: query
          description: The TPX protocol identifier
          required: true
          schema:
            $ref: '#/components/schemas/ModuleSpec'
      responses:
        '200':
          description: Parameters retrieved successfully.
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ParameterList'
                type: array
        '400':
          description: Any error when processing the request
        '401':
          description: Unauthorized - invalid api key or user not authorized for access
      security:
        - bearerAuth: []
          Dx-Admin: []
        - keycloak: []
      description: Retrieves the parameters corresponding to the provided TPX protocol identifier
      summary: Parameters retrieval
      tags:
        - Parameter
  /testPatterns:
    get:
      parameters:
        - name: tpxProtocolIdentifier
          in: query
          description: The TPX protocol identifier
          required: true
          schema:
            $ref: '#/components/schemas/ModuleSpec'
      responses:
        '200':
          description: Parameters retrieved successfully.
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/TestPattern'
                type: array
        '400':
          description: Any error when processing the request
        '401':
          description: Unauthorized - invalid api key or user not authorized for access
      security:
        - bearerAuth: []
          Dx-Admin: []
        - keycloak: []
      description: Retrieves the parameters corresponding to the provided TPX protocol identifier
      summary: Test patterns retrieval
      tags:
        - Test Pattern
servers:
  - url: '/location-profile-management/latest/api'
components:
  securitySchemes:
    bearerAuth:
      description: 'Enter your access token here without prefix "bearer " '
      type: http
      scheme: bearer
      bearerFormat: JWT
    keycloak:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: '/auth/realms//protocol/openid-connect/auth'
          scopes: {}
    Dx-Admin:
      type: oauth2
      description: |
        **This authorization is deprecated. Service account authentication should be used.**

        Enter your ThingPark credentials with dx-profile-id as prefix. 

        Example: dev1-api/test@abeeway.com
      flows:
        clientCredentials:
          tokenUrl: '/admin/latest/api/oauth/token'
          scopes: {}
  schemas:
    ComputedProfile:
      type: object
      required:
        - profile
        - computedFirmwareParameters
      properties:
        profile:
          $ref: '#/components/schemas/Profile'
        computedFirmwareParameters:
          type: array
          description: List of computed firmware parameters to be sent for the current profile
          items:
            $ref: '#/components/schemas/ComputedFirmwareParameter'
    ComputedFirmwareParameter:
      type: object
      required:
        - firmwareParameter
        - computedFirmwareParameters
        - computedHex
      properties:
        firmwareParameter:
          $ref: '#/components/schemas/FirmwareParameter'
        computedValue:
          type: integer
          format: int64
          description: Computed value to be saved in configuration file or sent over BLE
        computedHex:
          type: string
          description: the string representation of the hexadecimal value
    Profile:
      type: object
      required:
        - namespace
        - name
        - description
        - parameters
      properties:
        namespace:
          type: string
          description: Profile namespace. It can be a profile for ADA or for Mobile APP, or 'Subscriber' for specific subscriber profile namespace
        name:
          type: string
          description: Name identifying the profile (English language, should be unique in the namespace).
        id:
          type: integer
          description: Profile firmware identifier. It is set when the profile is a firmware hardcoded profile.
        description:
          type: string
          description: Profile description. (English language)
        translations:
          type: array
          description: Profile name and description translations (if any).
          items:
            $ref: '#/components/schemas/ProfileTranslation'
        parameters:
          type: object
          description: Parameters as defined in iot-flow-assettracker-driver AbeewayDownlinkPayload.setParameters
      description: Configuration profile of the tracker (up to 5 tracker parameters). A profile change can take up to 5 minutes to be taken into account.
    ProfileTranslation:
      type: object
      required:
        - language
        - name
        - description
      properties:
        language:
          type: string
          description: Translation language. Must be a ISO-639 code.
        name:
          type: string
          description: Profile name translation in the corresponding language.
        description:
          type: string
          description: Profile description translation in the corresponding language.
      description: Resource representing a profile translation.
    ParameterList:
      type: object
      required:
        - firmwareVersion
        - uplinkPort
        - firmwareParameters
      description: Defines the list of parameters available by firmware version.
      properties:
        firmwareVersion:
          type: string
          description: Defines the firmware version.
        uplinkPort:
          type: integer
          description: Defines the uplink port.
        firmwareParameters:
          type: array
          items:
            $ref: '#/components/schemas/FirmwareParameter'
    FirmwareParameter:
      type: object
      required:
        - driverParameterName
        - id
        - description
        - defaultValue
        - compatibleTrackerModels
      description: Defines the firmware parameter.
      properties:
        driverParameterName:
          type: string
          description: Parameter name in the asset tracker driver.
        firmwareConfigurationFileParameterName:
          type: string
          description: Parameter name in the firmware configuration file.
        id:
          type: integer
          description: LoRa identifier
        bleId:
          type: integer
          description: BLE identifier
        description:
          type: string
          description: Parameter description
        defaultValue:
          type: integer
          description: Represents the default value of the parameter. When there is no input parameter, the default value is used as the input.
        readOnly:
          type: boolean
          description: If set to true, the parameter value can not be changed.
        parameterType:
          $ref: '#/components/schemas/ParameterType'
        compatibleTrackerModels:
          type: array
          description: Represents the tracker model compatible with the parameter.
          items:
            $ref: '#/components/schemas/ModuleSpec'
    Range:
      type: object
      description: Defines the range of the parameter number.
      required:
        - minimum
        - maximum
      properties:
        minimum:
          type: number
          description: Represents an inclusive lower limit for a parameter value.
        maximum:
          type: number
          description: Represents an inclusive upper limit for a parameter value.
        exclusiveMinimum:
          type: boolean
          description: Indicates whether minimum is exclusive or not.
        exclusiveMaximum:
          type: boolean
          description: Indicates whether maximum is exclusive or not.
    ModuleSpec:
      type: object
      description: Defines the module specification. It is used to represent the TPDX protocol identifier and the tracker model.
      required:
        - producerId
        - moduleId
        - version
      properties:
        producerId:
          type: string
          description: Defines the producer identifier.
        moduleId:
          type: string
          description: Defines the module identifier.
        version:
          type: string
          description: Defines the version.
    BitMap:
      required:
        - type
        - valueFor
      type: object
      discriminator:
        propertyName: type
      description: The representation of a firmware parameter defined as a bitmap.
      properties:
        type:
          type: string
          description: Defines the bitmap type. Depending on the type, other attributes are required.
          enum:
            - BitMapValue
            - BitMapObject
        valueFor:
          type: string
          description: Defines the property name of the parameter.
    BitMapValue:
      allOf:
        - $ref: '#/components/schemas/BitMap'
        - type: object
          required:
            - bitShift
          description: The representation of a firmware parameter defined as a bitmap.
          properties:
            bitShift:
              type: integer
              description: The bit number to shift to the left to insert the value for the property defined in valueFor. The shift is applied starting from bit 0.
            inverted:
              type: boolean
              description: It is used to indicate that the value is bit inverted (e.g. value 2 of length 4 would be set as 13  - 0010 => 1101).
            length:
              type: number
              description: Length of the value in bits (default 1).
    BitMapObject:
      allOf:
        - $ref: '#/components/schemas/BitMap'
        - type: object
          required:
            - values
          description: The representation of a firmware parameter defined as a bitmap.
          properties:
            values:
              type: array
              description: The nested bitmaps for this object.
              items:
                $ref: '#/components/schemas/BitMap'
    Property:
      type: object
      description: Represents the property of the parameter defined as bitmap.
      discriminator:
        propertyName: type
      required:
        - name
        - type
      properties:
        name:
          type: string
          description: The property name
        description:
          type: string
          description: The property description
        type:
          type: string
          description: Defines the property type. Depending on the type, other attributes are required.
          enum:
            - PropertyString
            - PropertyObject
            - PropertyBoolean
            - PropertyNumber
    PropertyNumber:
      allOf:
        - $ref: '#/components/schemas/Property'
        - description: Defines a number property.
        - type: object
          required:
            - range
          properties:
            range:
              $ref: '#/components/schemas/Range'
            additionalRanges:
              type: array
              description: used when the parameters has several ranges
              items:
                $ref: '#/components/schemas/Range'
            additionalValues:
              type: array
              description: Represents the values that are out of range.
              items:
                type: number
            multiply:
              type: number
              description: Represents the number by which the parameter must be multiplied so that it is converted to the required unit.
    PropertyBoolean:
      allOf:
        - $ref: '#/components/schemas/Property'
        - type: object
        - description: Defines a boolean property.
    PropertyString:
      allOf:
        - $ref: '#/components/schemas/Property'
        - type: object
          required:
            - possibleValues
            - firmwareValues
        - description: Defines a string property.
          properties:
            possibleValues:
              type: array
              description: It is used to enumerate the possible parameter values.
              items:
                type: string
            firmwareValues:
              type: array
              description: It represents the firmware values. It enables the mapping of the content of possibeValues array.
              items:
                type: integer
    PropertyObject:
      allOf:
        - $ref: '#/components/schemas/Property'
        - type: object
          required:
            - properties
        - description: Defines an object property.
          properties:
            properties:
              type: array
              description: It is used if the parameter is composed of nested objects.
              items:
                $ref: '#/components/schemas/Property'
    ParameterType:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          description: Defines the parameter type. Depending on the type, other attributes are required.
          enum:
            - ParameterTypeNumber
            - ParameterTypeString
            - ParameterTypeBitMap
      discriminator:
        propertyName: type
    ParameterTypeNumber:
      allOf:
        - $ref: '#/components/schemas/ParameterType'
        - description: Defines the parameter which is a number type.
        - type: object
          required:
            - range
          properties:
            range:
              $ref: '#/components/schemas/Range'
            additionalRanges:
              type: array
              description: used when the parameters has several ranges
              items:
                $ref: '#/components/schemas/Range'
            additionalValues:
              type: array
              description: Represents the values that are out of range.
              items:
                type: number
            multiply:
              type: number
              description: Represents the number by which the parameter must be multiplied so that it is converted to the required unit.
    ParameterTypeString:
      allOf:
        - $ref: '#/components/schemas/ParameterType'
        - description: Defines the parameter which is a string type.
        - type: object
          required:
            - possibleValues
            - firmwareValues
          properties:
            possibleValues:
              type: array
              description: It is used to enumerate the possible parameter values.
              items:
                type: string
            firmwareValues:
              type: array
              description: It represents the firmware values. It enables the mapping of the content of possibeValues array. In the following example, the firmware value 1 represents the  "BLE_BEACONS" collection scan type. "possibleValues":[ "NO_COLLECTION_SCAN", "BLE_BEACONS", "WIFI_BSSID" ], "firmwareValues":[ 0, 1, 2 ]
              items:
                type: integer
    ParameterTypeBitMap:
      allOf:
        - $ref: '#/components/schemas/ParameterType'
        - description: Defines the parameter which is bitmap type.
        - type: object
          required:
            - properties
            - bitMap
          properties:
            bitMap:
              type: array
              description: Represents the firmware value for the parameter defined as bitmap.
              items:
                $ref: '#/components/schemas/BitMap'
            properties:
              type: array
              description: Represents the properties of the parameter.
              items:
                $ref: '#/components/schemas/Property'
    TestPattern:
      type: object
      required:
        - name
        - steps
      properties:
        name:
          type: string
          description: Test pattern name.
        id:
          type: string
          description: Test pattern identifier.
        successString:
          type: string
          description: String to display in case of success.
        failureString:
          type: string
          description: String to display in case of failure.
        steps:
          type: array
          description: Test pattern steps.
          items:
            $ref: '#/components/schemas/TestPatternStep'
      description: Object describing a test pattern to be run on a device.
    TestPatternStep:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          description: Defines the test pattern step type. Depending on the type, other attributes are required.
          enum:
            - TestPatternStepWriteGattParameter
            - TestPatternStepReadGattParameter
            - TestPatternStepGattCharacteristicWriteCommand
            - TestPatternStepGattCharacteristicWriteRequest
            - TestPatternStepGattCharacteristicRead
            - TestPatternStepWriteCli
            - TestPatternStepReadCli
      discriminator:
        propertyName: type
    TestPatternStepWriteGattParameter:
      allOf:
        - $ref: '#/components/schemas/TestPatternStep'
        - type: object
          required:
            - parameterId
            - parameterValue
          properties:
            parameterId:
              type: number
              description: ID of the GATT parameter to write.
            parameterValue:
              type: number
              description: Value of the GATT parameter to write.
      description: Test pattern step to write specified GATT parameter value.
    TestPatternStepReadGattParameter:
      allOf:
        - $ref: '#/components/schemas/TestPatternStep'
        - type: object
          required:
            - parameterId
            - expectedValue
          properties:
            parameterId:
              type: number
              description: ID of the GATT parameter to read.
            expectedValue:
              type: number
              description: Expected value of the GATT parameter to read.
      description: Test pattern step to read expected GATT parameter value.
    TestPatternStepGattCharacteristicWriteCommand:
      allOf:
        - $ref: '#/components/schemas/TestPatternStep'
        - type: object
          required:
            - serviceUuid
            - characteristicUuid
            - characteristicValue
          properties:
            serviceUuid:
              type: string
              description: UUID of the GATT service to write on.
            characteristicUuid:
              type: string
              description: UUID of the GATT characteristic to write.
            characteristicValue:
              type: string
              description: Value of the GATT characteristic to write (hexadecimal string).
      description: Test pattern step to write specified GATT characteristic without response.
    TestPatternStepGattCharacteristicWriteRequest:
      allOf:
        - $ref: '#/components/schemas/TestPatternStep'
        - type: object
          required:
            - serviceUuid
            - characteristicUuid
            - characteristicValue
            - expectedResponse
          properties:
            serviceUuid:
              type: string
              description: UUID of the GATT service to write on.
            characteristicUuid:
              type: string
              description: UUID of the GATT characteristic to write.
            characteristicValue:
              type: string
              description: Value of the GATT characteristic to write (hexadecimal string).
            expectedResponse:
              type: string
              description: Expected response to write request (hexadecimal string).
      description: Test pattern step to write specified GATT characteristic with response.
    TestPatternStepGattCharacteristicRead:
      allOf:
        - $ref: '#/components/schemas/TestPatternStep'
        - type: object
          required:
            - serviceUuid
            - characteristicUuid
            - expectedCharacteristicValue
          properties:
            serviceUuid:
              type: string
              description: UUID of the GATT service to read from.
            characteristicUuid:
              type: string
              description: UUID of the GATT characteristic to read.
            expectedCharacteristicValue:
              type: string
              description: Expected value of the GATT characteristic read (hexadecimal string).
      description: Test pattern step to read specified GATT characteristic.
    TestPatternStepWriteCli:
      allOf:
        - $ref: '#/components/schemas/TestPatternStep'
        - type: object
          required:
            - writeString
          properties:
            writeString:
              type: string
              description: String to write on CLI.
      description: Test pattern step to write a string on CLI.
    TestPatternStepReadCli:
      allOf:
        - $ref: '#/components/schemas/TestPatternStep'
        - type: object
          required:
            - expectedString
          properties:
            expectedString:
              type: string
              description: String expected to be read on CLI.
      description: Test pattern step to read expected string from CLI.