Skip to main content

Interact with Total Connect 2 alarm systems

Project description

Total-Connect-Client

Total-Connect-Client is a python client for interacting with the TotalConnect2 alarm system.

Started by @craigjmidwinter to add alarm support for his personal HomeAssistant set-up, with later contributions from others.

To use with Home Assistant, follow the instructions to set up Total Connect.

For command line or other uses, the package can be downloaded at PyPI.

The code currently supports:

  • Arming (away, stay, night)
  • Disarming
  • Getting panel status (armed, bypassed, etc)
  • Getting zone status (normal, fault, trouble, low battery, etc)

Zone Status

To see zones that are faulted (open), your Total Connect account must have “Sensor Activities” enabled. Your alarm monitoring company may charge an extra fee to enable this. If available, these can be found in the Total Connect 2 web portal at Notifications -> Sensor Activities. Alternately, they can be found in the Total Connect mobile app at More -> Settings -> Notifications -> Sensor Activities.

Troubleshooting

If you're having trouble with your system, or find an error message, we may ask you to submit information about your alarm system.

From Home Assistant

  • Go to https://<your_home_assistant>/config/integrations
  • Find the TotalConnect integration card and click on the three dots in the bottom right corner
  • Click on Download Diagnostics

From the command line

Do the following steps:

python3 -m total_connect_client username

If you want to easily put the info into a file for sharing:

  • python3 -m total_connect_client username > my_info.txt
  • Now the file my_info.txt in the same directory will hold all of that information

WARNING: the output of this command includes private information including your username and password. Carefully remove it before sharing with the developers or posting on Github.

Create an Issue on Github and post both your problem and your system information.

Why do we ask for this information? The TotalConnect API documentation provides little information on the status codes and other information it returns about your system. We developed as best we could using the codes our own systems returned. We have seen many times that other users with issues have different system status codes.

Also consider looking at the Total Connect system status to see if there is a system wide problem.

Developer Interface

If you're an end user, just install Home Assistant and things should just work.

If you're a developer and want to interface to TotalConnect from a system other than Home Assistant:

pip install total-connect-client
from total_connect_client import TotalConnectClient, ArmType, ArmingHelper

To arm or disarm the system you must provide the usercode. The usercodes dictionary maps locationid to usercode; if the locationid is not found it uses the default usercode.

usercodes = { 'default': '1234' }
client = TotalConnectClient(username, password, usercodes)

for location in client.locations:
    # location.arming_state can be matched against the ArmingState enum members
    # or you can call the ArmingState convenience methods:
    location.arming_state.is_disarmed()
    location.arming_state.is_armed() # true if system is armed in any way
    location.arming_state.is_armed_away()
    location.arming_state.is_pending() # true if system is arming or disarming
    location.arming_state.is_triggered() # true if system is in any alarm state
    location.arming_state.is_triggered_gas() # true if in carbon monoxide alarm state
    #    and many more convenience methods

    # you can pass one of the ArmType enum members to location.arm(), e.g.
    #    location.arm(ArmType.STAY_INSTANT)
    # or, equivalently, you can use any of the specific methods on ArmingHelper:
    #    ArmingHelper(location).arm_away()

    location.disarm()

    location.zone_bypass(zoneid)

    location.is_ac_loss()
    location.is_low_battery()
    location.is_cover_tampered()
    location.last_updated_timestamp_ticks
    location.configuration_sequence_number

    for (zone_id, zone) in location.zones.items():
        zone.is_bypassed()
        zone.is_faulted()
        zone.is_tampered()
        zone.is_low_battery()
        zone.is_troubled()
        zone.is_triggered()

        # zone.zone_type_id can be matched against the ZoneType enum members,
        # or you can call the following convenience methods:
        zone.is_type_button()
        zone.is_type_security()
        zone.is_type_motion()
        zone.is_type_fire() # heat detector or smoke detector
        zone.is_type_carbon_monoxide()
        zone.is_type_medical()

        zone.partition # the partition ID
        zone.description
        zone.can_be_bypassed
        zone.status
        zone.battery_level
        zone.signal_strength
        zone.chime_state
        zone.supervision_type
        zone.alarm_report_state
        zone.loop_number
        zone.sensor_serial_number
        zone.device_type

    # to refresh a location
    location.get_partition_details()
    location.get_zone_details()
    location.get_panel_meta_data()

    # to arm or disarm by partition
    for (partition_id, partition) in location.partitions.items():
        ArmingHelper(partition).arm_stay()
        etc.

Recent Interface Changes

  • Partition support has been added. The TotalConnectLocation.arm and disarm family of methods now accept an optional partition_id parameter, and a single TotalConnectPartition object has arm() and disarm() methods and can be used with ArmingHelper.
  • Previously most methods returned True on success and False on failure, with no exceptions expected. Now successful methods return but on failure raise subclasses of TotalConnectError.
  • The arming control methods in TotalConnectClient have been deprecated; instead use the similar methods on the values of self.locations.

Likely Future Interface Changes

  • Previously if the usercodes dictionary was invalid, the DEFAULT_USERCODE was silently used. In a future release, we will raise an exception on an invalid dictionary.

If there's something about the interface you don't understand, check out the Home Assistant integration that uses this package, or submit an issue.

During development, if you discover new status codes or other information not handled, please submit an issue to let us know, or even better submit a pull request.

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

total_connect_client-2024.5.tar.gz (37.8 kB view details)

Uploaded Source

Built Distribution

total_connect_client-2024.5-py3-none-any.whl (31.5 kB view details)

Uploaded Python 3

File details

Details for the file total_connect_client-2024.5.tar.gz.

File metadata

  • Download URL: total_connect_client-2024.5.tar.gz
  • Upload date:
  • Size: 37.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.0.0 CPython/3.11.2

File hashes

Hashes for total_connect_client-2024.5.tar.gz
Algorithm Hash digest
SHA256 5aec44c726e2329008001c34c8026636c705fee75492bb97647a98bd468ee3a4
MD5 b7674910dbf50adff1c5d1ae28b8a940
BLAKE2b-256 6faf77c0387bda2caa332220ac34e682bc9b70990f57dbb12a70493bc26407b4

See more details on using hashes here.

File details

Details for the file total_connect_client-2024.5-py3-none-any.whl.

File metadata

File hashes

Hashes for total_connect_client-2024.5-py3-none-any.whl
Algorithm Hash digest
SHA256 ce03a2a3bb50f1a609c8073bc21eea8772391f27fab32ce0f10f44d5f7442bbd
MD5 2adaa959d0f758eab40f442d566ceff7
BLAKE2b-256 fb140b7a2517fb8946da7842f3e868204c73b619ec8c99829d307b503cb7512e

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page