hiktools

https://hiktools.readthedocs.io/en/latest/
Admin
hiktools is a Python toolkit for working with Hikvision devices, providing firmware inspection and...
Tokens:4,110
Snippets:49
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Build Documentation

Source: https://hiktools.readthedocs.io/en/latest/index.html

Install Sphinx and build the HTML documentation for hiktools.

```bash
cd docs/
pip install -U sphinx
sphinx-build -b html source build
```

--------------------------------

### Clone and Install Hiktools

Source: https://hiktools.readthedocs.io/en/latest/index.html

Clone the hiktools repository and install it using pip.

```bash
git clone https://github.com/MatrixEditor/hiktools.git
cd hiktools/ && pip install .
```

--------------------------------

### Install Wireshark Dissector

Source: https://hiktools.readthedocs.io/en/latest/index.html

Copy the SADP Lua dissector to the Wireshark global Lua plugins directory. Ensure you replace $LOCATION with the actual path.

```bash
$LOCATION=""
# on unix
cp hiktools/lua/sadp.lua $LOCATION/sadp.lua
# on windows
copy "hiktools\lua\sadp.lua" "$LOCATION\sadp.lua"
```

--------------------------------

### SADPClient UDP Wrapper Example

Source: https://hiktools.readthedocs.io/en/latest/sadp.html

Demonstrates the usage of the SADPClient for sending data via UDP broadcast and iterating over received SADP messages. The client can be used with a 'with' statement for proper resource management.

```python
from hiktools import sadp

with sadp.SADPClient(timeout=3) as client:
  # send data with client.write
  client.write(some_message)

  # receive bytes with client.recv_next() or just iterate
  # over next SADPMessages:
  for message in client:
    if message is None: break
    # de-serialize message
    response = sadp.unmarshal(message)
```

--------------------------------

### UDP Broadcast Communication

Source: https://hiktools.readthedocs.io/en/latest/index.html

Interact with devices using UDP broadcast via the sadp module. This example shows creating an inquiry packet, sending it using SADPClient, and processing the responses, including extracting the device's IPv4 address.

```python
from hiktools import sadp
from uuid import uuid4

# create a packet from a simple dict object
inquiry = sadp.fromdict({
   'Uuid': str(uuid4()).upper(),
   'MAC': 'ff-ff-ff-ff-ff-ff',
   'Types': 'inquiry'
})

# Open up a client to communicate over broadcast
with sadp.SADPClient() as client:
   # send the inquiry packet
   client.write(inquiry)

   # iterate over all received packets (None is returned on error)
   for response in client:
      if response is None: break
      # initiate the response
      message = sadp.unmarshal(response.toxml())

      # message objects contain a dict-like implementation
      for property_name in message:
         print(message[property_name])

      # e.g.
      print('Device at', message['IPv4Address'])
```

--------------------------------

### DeviceSafeCodePacket Get Safecode

Source: https://hiktools.readthedocs.io/en/latest/sadp.html

Retrieves the safecode from a DeviceSafeCodePacket object. The safecode is returned as a SafeCode object.

```python
get_safecode() → SafeCode
    
    Returns the converted safecode as a SafeCode object.
```

--------------------------------

### Construct and Send an Inquiry Packet

Source: https://hiktools.readthedocs.io/en/latest/csadp.html

Demonstrates how to initialize a network service, build an inquiry packet, calculate its checksum, and send it over a specified interface.

```python
from hiktools import csadp

# Because the following module requires root priviledges it
# has to be imported directly.
from hiktools.csadp import CService

sock = CService.l2socket('wlan0')
counter = 0x115e

# To build an Inquiry packet, we need the following information:
# - our mac, ipv4 and ipv6 address (and the counter of course)
packet = csadp.Inquiry('<MAC>', '<IPv4>', '<IPv6>', counter)

# before we can send the message, a checksum has to be calculated
packet.insert_checksum()

sock.send(bytes(packet))
response = csadp.SADPPacket(sock.recv(1024))

# to view the contents just print the str() version
print(str(response))
```

--------------------------------

### Accessing and exporting DigiCap firmware files

Source: https://hiktools.readthedocs.io/en/latest/fmod.html

Use the DigiCap class to open and iterate through files in a .dav firmware package, and the export function to save them to a directory.

```python
from hiktools import fmod

 # Open the resource at the specified path (loading is done automatically)
 # or manually decrypt the firmware file.
 with fmod.DigiCap('filename.dav') as dcap:
    # Iterate over all files stored in the DigiCap object
    for file_info in dcap:
       print('> File name="%s", size=%d, pos=%d, checksum=%d' % file_info)

    # get file amount and current language
    print("Files: %d, Language: %d" % (dcap.head.files, dcap.head.language))

    # save all files stored in <filename.dav>
    fmod.export(dcap, "outdir/")
```

--------------------------------

### Usage of DigiCap for Firmware Modulation

Source: https://hiktools.readthedocs.io/en/latest/fmod.html

This snippet demonstrates how to use the DigiCap class from the hiktools.fmod module to open, iterate through, and export files from a firmware file (e.g., .dav).

```APIDOC
## Usage of DigiCap for Firmware Modulation

### Description
This example shows how to open a firmware file using `fmod.DigiCap`, iterate over its contents, access header information, and export all contained files to a specified directory.

### Method
This is a Python code example demonstrating library usage, not a direct API endpoint.

### Endpoint
N/A

### Parameters
N/A

### Request Example
```python
from hiktools import fmod

# Open the resource at the specified path (loading is done automatically)
# or manually decrypt the firmware file.
with fmod.DigiCap('filename.dav') as dcap:
    # Iterate over all files stored in the DigiCap object
    for file_info in dcap:
       print('> File name="%s", size=%d, pos=%d, checksum=%d' % file_info)

    # get file amount and current language
    print("Files: %d, Language: %d" % (dcap.head.files, dcap.head.language))

    # save all files stored in <filename.dav>
    fmod.export(dcap, "outdir/")
```

### Response
#### Success Response (N/A)
This is a code usage example, not an API response.

#### Response Example
N/A
```

--------------------------------

### Inspect and Extract Firmware

Source: https://hiktools.readthedocs.io/en/latest/index.html

Use the fmod.DigiCap class to inspect and export files from Hikvision firmware (.dav) files. The DigiCap object automatically loads the firmware, and fmod.export can save all contained files.

```python
from hiktools import fmod

# Open the resource at the specified path (loading is done automatically)
# or manually decrypt the firmware file.
with fmod.DigiCap('filename.dav') as dcap:
   # Iterate over all files stored in the DigiCap object
   for file_info in dcap:
      print('> File name="%s", size=%d, pos=%d, checksum=%d' % file_info)

   # get file amount and current language
   print("Files: %d, Language: %d" % (dcap.head.files, dcap.head.language))

   # save all files stored in <filename.dav>
   fmod.export(dcap, "outdir/")
```

--------------------------------

### hiktools.csadp.EthernetHeader

Source: https://hiktools.readthedocs.io/en/latest/csadp.html

Wrapper for raw ethernet message headers.

```APIDOC
## hiktools.csadp.EthernetHeader

### Description
Small wrapper for raw ethernet message headers.

### Parameters
- **dest** (str) - Required - The destination MAC address.
- **src** (str) - Required - The source MAC address.
- **eth_type** (int) - Required - The specified ethernet type (must be 0x8033).
```

--------------------------------

### hiktools.sadp Module Reference

Source: https://hiktools.readthedocs.io/en/latest/genindex.html

Overview of classes and methods available in the hiktools.sadp module for handling device communication and safe codes.

```APIDOC
## hiktools.sadp Module

### Description
Provides classes and methods for interacting with Hikvision SADP protocol, including packet handling and safe code generation.

### Classes
- **ActionResponse**: Represents the response from an action.
- **DeviceSafeCodePacket**: Handles packets related to device safe codes.
- **DiscoveryPacket**: Handles device discovery packets.
- **SADPClient**: Client for SADP protocol communication.
- **SafeCode**: Manages safe code properties and attributes.

### Methods
- **fromdict()**: Creates an object from a dictionary.
- **hik_code()**: Generates a Hikvision-specific code.
- **unmarshal()**: Deserializes data into objects.
```

--------------------------------

### EthernetHeader Structure

Source: https://hiktools.readthedocs.io/en/latest/csadp.html

Visual representation of the EthernetHeader byte structure.

```text
>>> +-------------------------------------------------+
>>> | EthernetHeader                                  |
>>> +---------------+--------------+------------------+
>>> | dest: byte[6] | src: byte[6] | eth_type: uint16 |
>>> +---------------+--------------+------------------+
```

--------------------------------

### hiktools.csadp Module Reference

Source: https://hiktools.readthedocs.io/en/latest/genindex.html

Overview of classes and methods available in the hiktools.csadp module for low-level packet manipulation.

```APIDOC
## hiktools.csadp Module

### Description
Provides low-level utilities for SADP packet construction, checksum calculation, and network address conversion.

### Classes
- **EthernetHeader**: Represents the Ethernet header structure.
- **SADPHeader**: Represents the SADP protocol header.
- **SADPPacket**: Represents a full SADP packet.
- **SADPPayload**: Represents the payload section of an SADP packet.

### Methods
- **get_checksum()**: Calculates the checksum for a packet.
- **insert_checksum()**: Inserts a calculated checksum into a packet.
- **payload()**: Retrieves or processes the packet payload.

### Network Utilities
- **inet6_iptos() / inet6_stoip()**: IPv6 address conversion.
- **inet_iptos() / inet_stoip()**: IPv4 address conversion.
- **inet_mactos() / inet_stomac()**: MAC address conversion.
```

--------------------------------

### SADPClient Class

Source: https://hiktools.readthedocs.io/en/latest/sadp.html

A UDP wrapper client for sending and receiving SADP broadcast messages.

```APIDOC
## SADPClient

### Description
A simple UDP wrapper client that implements basic functionalities for sending data via UDP broadcast and iterating over received SADP messages.

### Parameters
- **port** (int) - Optional - Default: 37020
- **timeout** (int) - Optional - Default: 2

### Request Example
```python
from hiktools import sadp
with sadp.SADPClient(timeout=3) as client:
  client.write(some_message)
  for message in client:
    if message is None: break
    response = sadp.unmarshal(message)
```
```

--------------------------------

### Send Raw SADP Packets (Linux)

Source: https://hiktools.readthedocs.io/en/latest/index.html

Utilize the CService.l2socket from hiktools.csadp to send raw SADP packets over a network interface. This requires root privileges and is Linux-specific. The code demonstrates building an inquiry packet and sending/receiving it.

```python
from hiktools import csadp

# Because the following module requires root priviledges it has to be
# imported directly
from hiktools.csadp import CService

sock = CService.l2socket('wlan0')
counter = 2855

# Building an inquiry packet
packet = csadp.packet(
   'src_mac', 'src_ip', 0x03, counter,
   checksum=csadp.from_counter(counter),
   payload='\x00'*28
)

# If you want to have the packet as an object use parse()
packet_obj = csadp.parse(packet)

sock.send(packet) # or sock.send(bytes(packet_obj))
response = csadp.parse(sock.recv(1024))
```

--------------------------------

### SADP Interface Methods

Source: https://hiktools.readthedocs.io/en/latest/sadp.html

Core utility functions for handling SADP XML data and generating device reset codes.

```APIDOC
## unmarshal(root)

### Description
Tries to de-serialize an XML-String into a qualified object instance.

### Parameters
#### Path Parameters
- **root** (xmltree.Element) - Required - The XML root element.

### Response
- **Returns** (BasicDictObject|None) - A qualified object instance (DiscoveryPacket, DeviceSafeCodePacket, ActionResponse) or None.

---

## hik_code(serial, timestamp)

### Description
Generates the old Hikvision reset code based on serial number and timestamp.

### Parameters
#### Path Parameters
- **serial** (str) - Required - The device’s serial number.
- **timestamp** (tuple) - Required - A timestamp in format (day, month, year).

### Response
- **Returns** (str) - The generated reset code.

---

## fromdict(value)

### Description
Converts a dictionary object into an SADPMessage object.

### Parameters
#### Request Body
- **value** (dict) - Required - The input dict containing the XML nodes.

### Response
- **Returns** (SADPMessage) - A message object containing all nodes converted into an XML string.
```

--------------------------------

### Generate Hikvision Reset Code

Source: https://hiktools.readthedocs.io/en/latest/sadp.html

Generates the old Hikvision reset code using a device's serial number and a timestamp. The generated code can be used within a reset packet.

```python
hiktools.sadp.hik_code(_serial : str_, _timestamp : tuple_) → str
    
    Generates the old Hikvision reset code.
    Arguments: :param serial: The device’s serial number. :type serial: str :param timestamp: A timestamp of the following format: (day, month, year) :type timestamp: str 

    Returns:
        
The generated reset code (can be used within a reset packet).

    Return type:
        
str
```

--------------------------------

### Register a Payload Class

Source: https://hiktools.readthedocs.io/en/latest/csadp.html

Uses the payload decorator to map a custom class to a specific packet type for the parsing process.

```python
>>> @payload(PACKET_TYPE['UpdateIP'])
>>> class MySADPPayload(SADPPayload):
...    pass
```

--------------------------------

### hiktools.csadp.get_checksum

Source: https://hiktools.readthedocs.io/en/latest/csadp.html

Calculates the SADP checksum for a given buffer.

```APIDOC
## hiktools.csadp.get_checksum

### Description
The SADP checksum algorithm implemented in python3.

### Parameters
- **buf** (UIntArray) - Required - An unsigned int16 array.
- **prefix** (int) - Required - The sender's type specification (0x42 for client, 0xf6 for server).

### Response
- **checksum** (int) - The calculated checksum value.
```

--------------------------------

### hiktools.csadp.SADPPacket.insert_checksum

Source: https://hiktools.readthedocs.io/en/latest/csadp.html

Calculates and inserts the checksum into an existing SADP packet.

```APIDOC
## SADPPacket.insert_checksum

### Description
Calculates the checksum for the current packet instance and updates the packet buffer.
```

--------------------------------

### Convert Dictionary to SADPMessage

Source: https://hiktools.readthedocs.io/en/latest/sadp.html

Converts a dictionary object into an SADPMessage object. The input dictionary should contain XML nodes.

```python
hiktools.sadp.fromdict(_value : dict_) → SADPMessage
    
    Converts a dict object into an SADPMessage object. 

    Parameters:
        
    **value** (_dict_) – The input dict containing the XML nodes. 

    Returns:
        
    An message object containing all nodes of the given dict object converted into an XML string. 

    Return type:
        
    SADPMessage
```
Tokens:
Raw