<!-- SPDX-FileCopyrightText: Copyright 2023 Jetperch LLC
SPDX-License-Identifier: Apache-2.0

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License. -->

<a id="time64"></a>

# time64

<a id="module-pyjoulescope_driver.time64"></a>

The Python time standard uses POSIX (UNIX) time which is defined relative
to Jan 1, 1970.  Python uses floating point seconds to express time.
This module defines a much simpler 64-bit fixed point integer for
representing time which is much friendlier for microcontrollers.
The value is 34Q30 with the upper 34 bits
to represent whole seconds and the lower 30 bits to represent fractional
seconds.  A value of 2\*\*30 (1 << 30) represents 1 second.  This
representation gives a resolution of 2 \*\* -30 (approximately 1 nanosecond)
and a range of +/- 2 \*\* 33 (approximately 272 years).  The value is
signed to allow for simple arithmetic on the time either as a fixed value
or as deltas.

For more details, see jsdrv/time.h.

### pyjoulescope_driver.time64.as_datetime(t)

Convert a time to a python UTC timestamp.

* **Parameters:**
  **t** – The time which can be:
  \* datetime.datetime
  \* python timestamp
  \* integer Joulescope timestamp

### pyjoulescope_driver.time64.as_isostr(t)

Convert a time to an ISO 8601 string.

* **Parameters:**
  **t** – The time in any format.
* **Returns:**
  The time string.

@see [https://en.wikipedia.org/wiki/ISO_8601](https://en.wikipedia.org/wiki/ISO_8601)

### pyjoulescope_driver.time64.as_time64(t)

Convert a time to a Joulescope timestamp.

* **Parameters:**
  **t** – The time which can be:
  \* datetime.datetime
  \* python timestamp
  \* integer Joulescope timestamp

### pyjoulescope_driver.time64.as_timestamp(t)

Convert a time to a python UTC timestamp.

* **Parameters:**
  **t** – The time which can be:
  \* datetime.datetime
  \* python timestamp
  \* integer Joulescope timestamp

### pyjoulescope_driver.time64.duration_to_seconds(d)

Convert a duration to float seconds.
:param d: The duration specification, which is one of:

> * A string formatted as fz where f is a valid floating-point value
>   and z is either omitted, ‘s’, ‘m’, ‘h’, ‘d’.
> * An integer in seconds.
> * A floating-point value in seconds.

### pyjoulescope_driver.time64.filename(extension=None, t=None)

Construct a filename from the time.

* **Parameters:**
  * **extension** – The filename extension, such as ‘.png’.
    None (default) uses ‘.jls’.
  * **t** – The time.  None (default) uses the current time.
* **Returns:**
  The filename.

### pyjoulescope_driver.time64.now()

Get the current timestamp.

* **Returns:**
  The time64 representation of the current time.
