Orange Mobile Belgium

Orange Home Assistant custom component. This custom component has been built from the ground up to bring your Orange mobile phone usage details into Home Assistant to help you towards a better follow up on your usage information. This integration is built against the public website provided by Orange Belgium.

For now only Belgian Mobile subscriptions are supported (the only ones I have). Feel free to extend via pull request.

This integration is in no way affiliated with Orange.

Installation

• HACS: HACS > Integration > add repo 'https://github.com/myTselectionPublic/orange' > search for Orange and install
• Restart Home Assistant
• Add 'Orange.be' integration via HA Settings > 'Devices and Services' > 'Integrations'
• Provide your Orange.be username and password. The integration performs the same SiteMinder form login and redirect handoff as the Orange customer-zone website; no browser session cookie is required.

Integration

This integration uses a Home Assistant DataUpdateCoordinator and polls the Orange Belgium customer zone every 30 minutes.

It creates:

• An account sensor with customer metadata, average invoice amount, account type, payment method, and discovered subscriptions.
• One subscription sensor per mobile number found in the Orange dashboard switcher, including plan name and billing/usage period dates.
• One balance sensor per usage block found on each subscription overview page. Known examples are surf volume, national calls, SMS, international calls/SMS, and employer-paid monthly amount.

Balance sensors expose the most useful value as their state:

• Remaining amount when Orange shows a remaining bundle value, for example 289.2 GB or 19.28 EUR.
• Consumed amount when Orange shows an unlimited bundle with consumed usage, for example 13 min or 0 SMS.

Common balance attributes include remaining, used, used_percentage, consumed, total, and orange_updated where available. Subscription sensors expose period_start, period_end, period_percentage, and days_remaining for the current billing period.

Status

Still some optimisations are planned, see Issues section in GitHub.

Debug logging

If the integration sets up but sensors stay empty, enable debug logging and restart Home Assistant:

logger:
  default: info
  logs:
    custom_components.orange: debug

Useful log lines start with Orange SSO, Fetched Orange page, Orange parsed overview page, Orange Belgium refresh parsed, and Creating Orange subscription sensors.

Technical pointers

The main logic and API connection related code can be found within:

• sensor.py
• utils.py -> Orange web client and dashboard parser

All other files just contain boilerplat code for the integration to work wtihin HA or to have some constants/strings/translations.

Example usage

Entity IDs depend on the mobile number and the balance labels returned by Orange. For a subscription 32486686824, the surf volume entity is expected to look like:

type: entities
entities:
  - entity: sensor.orange_32486686824_subscription
  - entity: sensor.orange_32486686824_surfvolume
  - entity: sensor.orange_32486686824_bellen_naar_alle_netwerken

Example markdown (replace phonenr with your phonenumber to match local sensor names)

type: vertical-stack
cards:
  - type: markdown
    content: >-
      ## <img
      src="https://raw.githubusercontent.com/myTselectionPublic/orange/custom_components/orange/brand/icon.png"
      width="30"/>&nbsp;&nbsp;Orange Telemeter

      ### Total used:
      {{state_attr('sensor.orange_phonenr_surfvolume','used_percentage')}}%
      ({{state_attr('sensor.orange_phonenr_surfvolume','used')}}GB of
      {{state_attr('sensor.orange_phonenr_surfvolume','total')}} GB)

      ####
      {{state_attr('sensor.orange_phonenr_subscription','days_remaining')}}
      days remaining
      ({{state_attr('sensor.orange_phonenr_surfvolume','remaining')}}GB)


      Period
      {{state_attr('sensor.orange_phonenr_subscription','period_start') |
      as_timestamp | timestamp_custom("%d-%m-%Y")}} -
      {{state_attr('sensor.orange_phonenr_subscription','period_end') |
      as_timestamp | timestamp_custom("%d-%m-%Y")}} 

      {{state_attr('sensor.orange_phonenr_subscription','plan')}}

      Laatste update:
      *{{state_attr('sensor.orange_phonenr_subscription','last_update') |
      as_timestamp | timestamp_custom("%d-%m-%Y %H:%M")}}*
  - type: custom:dual-gauge-card
    title: false
    min: 0
    max: 100
    shadeInner: true
    cardwidth: 350
    outer:
      entity: sensor.orange_phonenr_surfvolume
      attribute: used_percentage
      label: used
      min: 0
      max: 100
      unit: "%"
      colors:
        - color: var(--label-badge-green)
          value: 0
        - color: var(--label-badge-yellow)
          value: 60
        - color: var(--label-badge-red)
          value: 80
    inner:
      entity: sensor.orange_phonenr_subscription
      label: period
      attribute: period_percentage
      min: 0
      max: 100
      unit: "%"
  - type: history-graph
    entities:
      - entity: sensor.orange_phonenr_surfvolume
    hours_to_show: 500
    refresh_interval: 60