API Overview

Several of the modules may be useful for other software. Class OlympiaCamera communicates with the camera. This class allows to send commands to the camera and it converts the camera’s XML responses into Python dicts. These member functions are particularly useful:

from olympuswifi.camera import OlympiaCamera

camera = OlympiaCamera()

Upon initialization the OlympiaCamera class issues command get_commandlist and uses this information about all the camera commands and command options to check further requests to the camera.

camera.send_command('command', option1=value, ...)

Sends the command to the camera and returns a requests.Response object if successful. On error, it will print an error message and return None.

camera.xml_query('command', option1=value1, ...)

Sends a command to the camera, parses the XML result and returns the result as a Python dict. In case of an error it will print an error message and return None. To obtain the AGPS expiration date as in the example above, we can call camera.xml_query(‘get_agpsinfo’)[‘expiredate’] to get the result 20221111 as a string.

camera.set_clock()

Sets date and time.

camera.get_images()

Returns a list of all images on the camera. For each each image there is the file name including directory path, the size in bytes, and the date and time in ISO format.

camera.download_thumbnail('/DCIM/100OLYMP/PA220001.JPG')
camera.download_image('/DCIM/100OLYMP/PA220001.JPG')

Returns the image thumbnail and the full image respectively.

Detailed API Documentation

Module camera

class olympuswifi.camera.OlympusCamera

Class OlympusCamera communicates with an Olympus camera via wifi. It needs to run on a computer that is connected to the camera’s wifi network.

The communication via wifi with an Olympus camera is described here: OPC Communication Protocol 1.0a

Camera commands vary from camera model to camera model. The camera is queried for its list of supported commands and their arguments.

class CamMode(value): An enumeration.

class CamStatus(cammode_current: enum.Enum, liveview_active: bool, liveview_restart: bool, liveview_lvqty: str, liveview_port: int, execution_lock: threading.Semaphore)

class CmdDescr(method: str, args: Dict[str, dict | None])

Description of a single camera command.

args: Dict[str, dict | None]: nested dicts of command’s key-value argument pairs

method: str: HTTP-method get or post

class FileDescr(file_name: str, file_size: int, date_time: str)

This class describes an image file available for download.

date_time: str: ISO date and time, no timezone

file_name: str: example ‘/DCIM/100OLYMP/P1010042.JPG’

file_size: int: in bytes

HEADERS = {'Host': '192.168.0.10', 'User-Agent': 'OI.Share v2'}: Headers to send when communicating with camera.

URL_PREFIX = 'http://192.168.0.10/': This is the camera’s URL when the computer is connected to the camera’s wifi.

check_valid_command(command: str, args: Dict[str, CmdDescr]) → None

Check validity of command and arguments.

Parameters:

command (str) – camera command
args (Dict[str, CmdDescr]) – dict of command arguments

Raises:

raises RequestError if not a valid camera command

commandlist_cmds(parent: Element) → Dict[str, dict | None] | None: Parse commands in the XML output of command get_commandlist.

commandlist_params(parent: Element) → Dict[str, dict | None]: Parse parameters in the XML output of command get_commandlist.

download_image(dir: str) → bytes

Returns full-size jpeg image.

Parameters:: dir (str) – path to image on camera
Returns:: JPEG image

download_thumbnail(dir: str) → bytes

Returns a thumbnail jpeg image.

Parameters:: dir (str) – path to image on camera
Returns:: JPEG image

get_camera_info() → Dict[str, str]: Return a dict with an entry for ‘model’, the camera model.

get_camera_model() → str: Return the camera model.

get_camprop(propname: str) → str

Get the value of camera property. A dict of all supported property names can be obtained with:

get_commands()[‘get_camprop’].args[‘com’][‘get’][‘propname’]

Parameters:: propname (str) – supported property name
Raises:: raises RequestError if not a valid camera property
Returns:: value of propname

get_commands() → Dict[str, CmdDescr]: Return dict of permitted commands. Each command maps to an instance of class CmdDescr which holds the HTTP-method (‘get’ or ‘post’) and nested dicts that represent supported command arguments and their values; obtained from the camera with command ‘get_commandlist’.

get_settable_propnames_and_values() → Dict[str, List[str]]: Return dict of camera properties and list of their supported values.

get_supported() → Set[str]: Return a set of supported funcs; obtained from the camera with command ‘get_commandlist’.

get_versions() → Dict[str, str]: Return a dict with version info; obtained from the camera with command ‘get_commandlist’.

list_images(dir: str = '/DCIM') → List[FileDescr]

Return list of instances of class FileDescr for a given directory and all its subdirectories on the camera memory card.

Parameters:: dir (str) – camera’s image directory, default ‘/DCIM’
Returns:: list of instances of class FileDescr

report_model() → None

Report camera model and version info.

Returns:: Nothing; the camera model and version are written to stdout.

send_command(command: str, **args) → Response

Send command to camera; return Response object or None.

Parameters:

command (str) – camera command
args (Dict[str,CmdDescr]) – dict of command arguments

set_camprop(propname: str, value: str) → None

Set the value of camera property. A dict of all supported property names can be obtained with:

get_settable_propnames_and_values()

The list of supported values for property propname can be obtained with:

get_settable_propnames_and_values()[propname]

Parameters:

propname (str) – supported property name
value (str) – value for propname

Raises:

raises RequestError if not a valid camera property or value

set_clock() → None: Set the camera clock to this computer’s time.

start_liveview(port: int, lvqty: str) → List[str]

Start the liveview; the camera will broadcast an RTP live stream at the given UDP port in the given resolution. Supported values for the resolution can be queried with method:

get_commands()[‘switch_cammode’].args[‘mode’][‘rec’][‘lvqty’]

Parameters:

port (int) – UDP port for camera to broadcast RTP packages
lvqty (str) – resolution of live stream

Returns:

list of funcid names that will be in the RTP extension.

stop_liveview() → None: Stop the liveview; the camera will no longer send the RTP live stream.

take_picture() → None: The camera takes a picture.

xml2dict(xml: Element, parent: Dict[str, str]) → List[Dict[str, str]]

Recursively traverse XML and return a list of dicts.

Parameters:

xml – XML element
parent (Dict[str, str]) – parent directory

Returns:

Dict[str,str] or List[Dict[str,str]]

xml_query(command: str, **args) → Dict[str, str] | List[Dict[str, str]] | None

Send a command and return XML response as dict or list of dicts.

Parameters:

command (str) – camera command
args (Dict[str,CmdDescr]) – dict of command arguments

Returns:

Dict[str,str], List[Dict[str,str]], or None

xml_response(response: Response) → Dict[str, str] | List[Dict[str, str]] | None

Turn an XML response into a dict or a list of dicts.

Parameters:: response (requests.Response) – requests response object
Returns:: Dict[str,str], List[Dict[str,str]], or None

exception olympuswifi.camera.RequestError(msg: str)

Exception for error in camera command request.

Parameters:: msg (str) – error message

exception olympuswifi.camera.ResultError(msg: str, response: Response)

Exception for error returned by camera.

Parameters:

msg (str) – error message
response (requests.Response) – requests response object

Module download

olympuswifi.download.download_photos(camera: OlympusCamera, output_dir: str) → None

Function download_photos() downloads photos from the Olympus camera.

Parameters:: output_dir (str) – local directory to write downloaded camera images to
Returns:: nothing; warnings are written to stdout

olympuswifi.download.main() → None: Main program for script olympus-download. Parses command-line arguments and calls APIs.

Module liveview

class olympuswifi.liveview.LiveViewReceiver(img_queue: SimpleQueue)

Class LiveViewReceiver receives the camera’s live view and appends it as sequence of JPEG images to a queue.

Parameters:: img_queue (queue.SimpleQueue) – instances of JPEGandExtension are appended to this queue

JPEG_END = b'\xff\xd9': JPEG images end with this magic number

JPEG_START = b'\xff\xd8': JPEG images start with this magic number

class JPEGandExtension(jpeg: bytes, extension: bytes)

This class stores a JPEG image and and RTP extension. Instances of this class are appended to the queue.

extension: bytes: RTP extension

jpeg: bytes: JPEG image

MAX_QUEUE_SIZE = 50: The queue will not contain more than this many entries

decode_RTP(packet: bytes) → Tuple[int, int, bytes]

Decodes an RTP packet stores extension in self.extension and extracts marker, sequence number, and payload.

Based on: https://en.wikipedia.org/wiki/Real-time_Transport_Protocol

Parameters:: packet (bytes) – packet received from camera consisting of JPEG image and RTP entension
Returns:: triple consisting of marker, sequence_number, and payload

init_frame(valid: bool = True) → None

Start a frame; called when marker bit seen.

Parameters:: valid (bool) – is frame valid; frames are valid when they have the expected sequence number

process_frame(frame: bytes) → None

Appends frame - a JEPG image - and extension from self.extension to queue.

Parameters:: frame (bytes) – frame received from camera

process_packet(packet: bytes) → None

Assembles multiple packets into one frame. Calls process_frame with each frame.

Based on: https://stackoverflow.com/questions/7665217 where we are dealing here with MJPEG, not H264.

Parameters:: packet (bytes) – packet received from camera consisting of JPEG image and RTP entension

receive_packets(port: int) → None

This main loop receives RTP packets from the camera. It runs in a thread in parallel to the gui.

Parameters:: port (int) – port to listen to for RTP packages from the camera

shut_down(): Request showdown of this LiveViewReceiver thread.

class olympuswifi.liveview.LiveViewWindow(camera: OlympusCamera, port: int = 40000)

Class LiveViewWindow displays the camera’s live view in a window.

Parameters:

camera (OlympusCamera) – connection to Olympus camera; instance of class OlympusCamera
port (int) – port to listen to for RTP packages from the camera

class CamPropInfo(name: str, values: list, cur_val: int, variable: IntVar)

Information about a camera property.

cur_val: int: current value, index into list of strings

name: str: camprop name

values: list: values, list of strings

variable: IntVar: variable being watched for changes

UPDATE_INTERVAL = 25: The queue is checked every this many milliseconds for a new frame.

check_update_image() → None: A timer calls this method periodically. It checks the queue for a new image and if there is one updates the window.

get_orientation(extension: bytes) → int | None

Get orientation from RTP extension. Its values are the same as in EXIF: 1 for 0°, 3 for 180°, 6 for 90° clockwise, and 8 for 270° clockwise.

Parameters:: extension (bytes) – RTP extension
Returns:: 1, 3. 6, 8, or None.

next_image() → PIL.ImageTk.PhotoImage

This method returns the next image from the queue.

Returns:: ImageTk.PhotoImage

on_camprop(var_name: str, *dummy) → None

Called when a camprop variable is written to.”

Parameters:

var_name (str) – camera property name
dummy – ignored

on_lvqty(*args) → None

Called when self.lvqty_var is written to.

Parameters:: args – ignored

power_off_and_exit(): Turn camera off and exit.

set_clock()

Set camera clock.

The live view is stopped before setting the clock and restarted afterwards.

take_pic() → None: Take a picture.

olympuswifi.liveview.main() → None: Main program for script olympus-liveview. Parses command-line arguments and displays liveview window.

Module main

olympuswifi.main.main() → None: Main program for script olympus-camera. Parses command-line arguments and calls APIs.

olympuswifi.main.user_command(camera: OlympusCamera, cmd: str) → bool

Sends user-supplied command to camera, supports output redirection. Writes error messages to stderr and returns True on error.

Parameters:

camera (OlympusCamera) – connection to Olympus camera; instance of class OlympusCamera
cmd (str) – one command with optional output redirection

Returns:

True on error, False otherwise

Module log2gpx

class olympuswifi.log2gpx.TrackPoint(latitude: float, longitude: float, elevation: str, iso_time: str): Single point of a GPS Track. Tracks are represented as lists of TrackPoint.

olympuswifi.log2gpx.main() → None: Main program for script olympus-log2gpx. Parses command-line arguments and converts GPS log.

olympuswifi.log2gpx.read_log(fn: str) → List[TrackPoint]

Read an Olympus .LOG file and return a list of TrackPoint.

Parameters:: fn (str) – File name to read.
Returns:: list of TrackPoint; empty list when file does not contain a GPS track

olympuswifi.log2gpx.write_gpx(fn: str, track: List[TrackPoint]) → None

Write a list of TrackPoint to a .gpx file.

Parameters:

fn (str) – File name to write.
track (List[TrackPoint]) – list of instances of class TrackPoint

Returns:

list of TrackPoint