NAME
IPCamera::Reolink - Reolink API provides access to the System, Security, Network, Video input, Enc, Record, PTZ, and Alarm functions of a Reolink IP Camera or NVR via HTTP(S)/REST
VERSION
1.03
SYNOPSIS
use IPCamera::Reolink;
my $camera_url = "http://192.168.1.160";
my $camera_user_name = "vlc"; # non-admin user recommended
my $camera_password = 'this-is-a-bad-password';
my $camera = IPCamera::Reolink->new($camera_url, $camera_user_name, $camera_password);
# or
# my $camera = IPCamera::Reolink->new( {camera_url => $camera_url_http, camera_user_name => $camera_user_name, camera_password => $camera_password, camera_x509_certificate_file => undef, camera_x509_key_file => undef, camera_certificate_authority_file => undef, })
# Optionally Login to the camera immmediately to validate the camera URL and credentials, otherwise a Login will be implicitly performed by the API on the first camera command.
die "IPCamera::Reolink::Login failed" if(!$camera->Login());
# Some camera info
my $devinfo_r = $camera->GetDevInfo();
print "Camera model : " . $devinfo_r->{model} . "\n";
print "Camera name : " . $devinfo_r->{name} . "\n";
# Camera presets
my($ptzpreset_value_r, $ptzpreset_range_r, $ptzpreset_initial_r) = $camera->GetPtzPreset(IPCamera::Reolink::ChannelDefault);
my $ptzpresets_r = $ptzpreset_value_r->{PtzPreset};
foreach my $ptzpreset (@$ptzpresets_r){
my $enable = $ptzpreset->{enable};
if($enable){
my $preset_id = $ptzpreset->{id};
$camera->PtzCtrl(IPCamera::Reolink::ChannelDefault, IPCamera::Reolink::PTZ_ToPos, IPCamera::Reolink::PTZ_SpeedMax, $preset_id);
} # if
} # foreach
# Start a camera pan to the left.
$camera->PtzCtrl(IPCamera::Reolink::ChannelDefault, IPCamera::Reolink::PTZ_Left, IPCamera::Reolink::PTZ_SpeedMax);
# Times passes, stop the last camera PTZ function.
$camera->PtzCtrl(IPCamera::Reolink::ChannelDefault, IPCamera::Reolink::PTZ_Stop, IPCamera::Reolink::PTZ_SpeedMin);
# Camera snapshot
my $jpg_image_data = $camera->Snap(IPCamera::Reolink::ChannelDefault);
die "IPCamera::Reolink::Snap() failed\n" if(!defined($jpg_image_data));
my $now = time();
my($sec, $min, $hour, $dd, $mon, $yr, $wday, $yday, $isdst) = localtime($now);
($dd < 10) && ($dd = "0" . $dd);
my $mm = $mon + 1;
($mm < 10) && ($mm = "0" . $mm);
($hour < 10) && ($hour = "0" . $hour);
my $yyyy = $yr + 1900;
my $file_name = sprintf("%04d%02d%02d-%2s%02d%02d.jpg", $yyyy, $mm, $dd, $hour, $min, $sec);
my $fh;
open $fh, ">$file_name" || die("open($file_name) failed - $!");
my $l = length($jpg_image_data);
(syswrite($fh, $jpg_image_data, $l) == $l) || die("syswrite($file_name, $l) failed - $!\n");
close($fh);
# Play Audio Alarm 1 time
my $r = $camera->AudioAlarmPlay(IPCamera::Reolink::ChannelDefault, 0, 1, IPCamera::Reolink::AAP_AlarmModeTimes);
# Logout of camera
$camera->Logout();DESCRIPTION
IPCamera::Reolink provides a simple way to interact with Reolink IP cameras and NVRs via the device HTTP(S)/REST interface.
Based on the "Reolink Camera API User Guide_V8 (Updated in April 2023)" document, available here:
https://github.com/mnpg/Reolink_api_documentations
As the author is primarily interested in accessing the Pan/Tilt/Zoom (PTZ) functions of his Reolink RLC-823A-16x IP camera, only the subset of functions described in the above document needed to access these features have been implemented.
Other functions may be added in the future based on the need/whims of the author and requests from other (if any) users of this module.
ATTRIBUTES
DEBUG
Set $IPCamera::Reolink::DEBUG to a value > 0 for increasingly detailed debug output to STDERR.
default is 0 for no debug output.
- DEBUG = 0
-
No debug output
- DEBUG = 1
-
Log camera REST/JSON requests and responses.
- DEBUG = 2
-
Log camera REST/JSON request and response times.
VERSION
$IPCamera::Reolink::VERSION is the version of this module.
IPCamera::Reolink::ChannelDefault
IPCamera::Reolink::ChannelDefault is the default Reolink channel (0).
IPCamera::Reolink::PtzCtrl() op values.
- IPCamera::Reolink::PTZ_Stop
-
PTZ stop turning.
- IPCamera::Reolink::PTZ_Left
-
PTZ turn left at the specified speed.
- IPCamera::Reolink::PTZ_Right
-
PTZ turn right at the specified speed.
- IPCamera::Reolink::PTZ_Up
-
PTZ turn up in the specified speed.
- IPCamera::Reolink::PTZ_Down
-
PTZ turn down at the specified speed.
- IPCamera::Reolink::PTZ_LeftUp
-
PTZ turn left-up at the specified speed.
- IPCamera::Reolink::PTZ_LeftDown
-
PTZ turn left-down at the specified speed.
- IPCamera::Reolink::PTZ_RightUp
-
PTZ turn right-up at the specified speed.
- IPCamera::Reolink::PTZ_RightDown
-
PTZ turn right-down at the specified speed.
- IPCamera::Reolink::PTZ_IrisDec
-
Iris shrink at the specified speed.
- IPCamera::Reolink::PTZ_IrisInc
-
Iris enlarge at the specified speed.
- IPCamera::Reolink::PTZ_ZoomDec
-
Zoom in at the specified speed.
- IPCamera::Reolink::PTZ_ZoomInc
-
Zoom out at the specified speed.
- IPCamera::Reolink::PTZ_FocusDec
-
Focus backwards at the specified speed.
- IPCamera::Reolink::PTZ_FocusInc
-
Focus forwards at the specified speed.
- IPCamera::Reolink::PTZ_Auto
-
PTZ turn auto at the specified speed.
- IPCamera::Reolink::PTZ_StartPatrol
-
PTZ patrol at the specified speed.
- IPCamera::Reolink::PTZ_StopPatrol
-
PTZ stop patrol.
- IPCamera::Reolink::PTZ_ToPos
-
PTZ turn to the specified preset at the specified speed.
IPCamera::Reolink::PtzCtrl() speed values.
- IPCamera::Reolink::PTZ_SpeedMin => 1;
- IPCamera::Reolink::PTZ_SpeedMax => 64;
- IPCamera::Reolink::PTZ_SpeedHalf => 32;
IPCamera::Reolink::PtzCtrl() preset values.
IPCamera::Reolink::StartZoomFocus() op ZoomPos values.
IPCamera::Reolink::StartZoomFocus() op FocusPos values.
IPCamera::Reolink:SetOsd() pos values.
- IPCamera::Reolink::OSD_UpperLeft => "Upper Left";
- IPCamera::Reolink::OSD_TopCenter => "Top Center";
- IPCamera::Reolink::OSD_UpperRight => "Upper Right";
- IPCamera::Reolink::OSD_LowerLeft => "Lower Left";
- IPCamera::Reolink::OSD_BottomCenter => "Bottom Center";
- IPCamera::Reolink::OSD_LowerRight => "Lower Right";
- IPCamera::Reolink::OSD_OtherConfiguration => "Other Configuration";
IPCamera::Reolink:AudioAlarmPlay() alarm_mode values.
- AAP_AlarmModeTimes => "times";
-
play # times specified by times
- AAP_AlarmModeManual => "manu";
-
play continuously until next AudioAlarmPlay command
PTZ_op_list
$IPCamera::Reolink::PTZ_op_list is the IPCamera::Reolink::PtzCtrl() op values as list.
PTZ_speed_list
$IPCamera::Reolink::PTZ_speed_list is the IPCamera::Reolink::PtzCtrl() speed values as list.
PTZ_preset_list
$IPCamera::Reolink::PTZ_preset_list is the IPCamera::Reolink::PtzCtrl() preset values as list.
PTZ_ZoomPos_list
$IPCamera::Reolink::PTZ_ZoomPos_list is the IPCamera::Reolink::StartZoomFocus() zoom pos values as list.
PTZ_FocusPos_list
$IPCamera::Reolink::PTZ_FocusPos_list is the IPCamera::Reolink::StartZoomFocus() focus pos values as list.
OSD_pos_list
$IPCamera::Reolink::OSD_pos_list is the IPCamera::Reolink::SetOsd() pos values as list.
AAP_AlarmMode_list
IPCamera::Reolink::AAP_AlarmMode_list is the IPCamera::Reolink::AudioAlarmPlay() alarm_mode values as list.
METHODS
new({camera_url => "http://192.168.1.99/", camera_user_name => "admin", camera_password => "password", camera_x509_certificate_file => undef, camera_x509_key_file => undef, camera_certificate_authority_file => undef, })
new($camera_url, $camera_user_name, $camera_password)
Construct a new IPCamera::Reolink object.
Takes the following manditory parameters:
- $camera_url
-
The camera URL for access via HTTP(S), i.e. "http://192.168.1.123".
- $camera_user_name
-
The camera account name for access via HTTP(S), i.e. "vlc".
You should set up a non admin acccount for access via this API, the admin account will work as well but is not recommended.
But just to complicate things, certain methods (described below) require admin access to use with the current version of the camera firmware.
Reolink may fix this in the future.
- $camera_password
-
The camera account password for access via HTTP(S), i.e. "this-is-a-bad-password".
- $camera_x509_certificate_file
-
TBD.
- $camera_x509_key_file
-
TBD.
-
TBD.
Login()
Login to the camera using the credentials provided to new() (above).
Upon successful Login the camera passes back a Login token and lease time that is used internally by other IPCamera::Reolink camera API methods.
The token is valid for the specified lease time.
IPCamera::Reolink will manage the Login token and will call Login() internally as needed when the Login token expires.
This should all be invisible to the caller.
- return
-
Returns (undef, undef) if the Login was rejected by the camera.
Returns ($camera_login_token, $camera_login_lease_time) if the Login is successful, where $camera_login_token is the token passed to other API methods and $camera_login_lease_time is the time in seconds for which the token is valid, after which a new token must be aquired.
Usually the caller is not interested in these values as they are used internally by IPCamera::Reolink.
Logout()
Release Login() credentials.
- return
-
Returns 1 if Logout() succeeded else 0 (zero) on failure, typically if Login() not called.
GetChannelstatus()
Return camera/NVR per channel status.
- return
-
Returns ($count, $status_r) if GetChannelstatus() succeeded.
- $count
-
The number of channels in the camera/NVR, typically 1 for a camera.
The number of elements in the @status array.
- $status_r
-
reference to Per channel status array with $count elements.
Returns (undef, undef) if GetChannelstatus() failed.
GetDevInfo()
Return useful information about the camera.
- return
-
Returns undef if the GetDevInfo function failed.
Returns $devinfo_r hash reference to device information if successful, fields most likely subject to change (typical values in parenthesis):
- $devinfo_r->{audioNum} (1)
-
The number of audio channels.
- $devinfo_r->{B485} (0)
-
0: no 485, 1: have 485
- $devinfo_r->{buildDay} ("build 23061923")
-
The establish date.
- $devinfo_r->{cfgVer} ("v3.1.0.0")
-
The version number of configuration information.
- $devinfo_r->{channelNum} (1)
-
The number of channels.
- $devinfo_r->{detail} ("IPC_523SD10S16E1W01100000001")
-
The details of device information.
- $devinfo_r->{diskNum} (1)
-
The number of USB disk or SD card.
- $devinfo_r->{exactType} ("IPC")
-
Product type.
- $devinfo_r->{firmVer} ("v3.1.0.2347_23061923_v1.0.0.93")
-
The version number of the firmware.
- $devinfo_r->{frameworkVer} (1)
-
Architecture version.
- $devinfo_r->{hardVer} ("IPC_523SD10")
-
The version number of the hardware.
- $devinfo_r->{IOInputNum} (0)
-
The number of IO input port.
- $devinfo_r->{IOOutputNum} (0)
-
The number of IO output port.
- $devinfo_r->{model} ("RLC-823A 16X")
-
Camera/NVR model.
- $devinfo_r->{name} ("rlc-823a-16x")
-
Device name.
- $devinfo_r->{pakSuffix} ("pak,paks")
-
?
- $devinfo_r->{serial} ("00000000000000")
-
?
- $devinfo_r->{type} ("IPC")
-
Device type.
- $devinfo_r->{wifi} (0)
-
0: no WIFI, 1: have WIFI.
PtzCtrl($camera_channel, $camera_operation, $camera_operation_speed, $camera_preset_id)
Control camera PTZ functions.
Upon successful return the camera asynchronously executes the requested operation until another operation is specified by PtzCtrl() or until the camera limit is reached for the specified operation, for example the camera has tilted as far Down as physically possible.
Some operations like IPCamera::Reolink::PTZ_Left will execute forever until another PtzCtrl command is executed.
- return
-
Returns 1 if PtzCtrl() succeeded else 0 (zero) on failure, typically due to using non-admin account for admin access operations.
- $camera_channel
-
Perform camera operation on specified camera channel:
- $camera_operation
-
Camera operation to perform:
- IPCamera::Reolink::PTZ_Stop
-
PTZ stop turning.
- IPCamera::Reolink::PTZ_Left
-
PTZ turn left at the specified speed.
- IPCamera::Reolink::PTZ_Right
-
PTZ turn right at the specified speed.
- IPCamera::Reolink::PTZ_Up
-
PTZ turn up in the specified speed.
- IPCamera::Reolink::PTZ_Down
-
PTZ turn down at the specified speed.
- IPCamera::Reolink::PTZ_LeftUp
-
PTZ turn left-up at the specified speed.
- IPCamera::Reolink::PTZ_LeftDown
-
PTZ turn left-down at the specified speed.
- IPCamera::Reolink::PTZ_RightUp
-
PTZ turn right-up at the specified speed.
- IPCamera::Reolink::PTZ_RightDown
-
PTZ turn right-down at the specified speed.
- IPCamera::Reolink::PTZ_IrisDec
-
Iris shrink at the specified speed.
- IPCamera::Reolink::PTZ_IrisInc
-
Iris enlarge at the specified speed.
- IPCamera::Reolink::PTZ_ZoomDec
-
Zoom in at the specified speed.
- IPCamera::Reolink::PTZ_ZoomInc
-
Zoom out at the specified speed.
- IPCamera::Reolink::PTZ_FocusDec
-
Focus backwards at the specified speed.
- IPCamera::Reolink::PTZ_FocusInc
-
Focus forwards at the specified speed.
- IPCamera::Reolink::PTZ_Auto
-
PTZ turn auto at the specified speed.
- IPCamera::Reolink::PTZ_StartPatrol
-
PTZ patrol at the specified speed.
- IPCamera::Reolink::PTZ_StopPatrol
-
PTZ stop patrol.
- IPCamera::Reolink::PTZ_ToPos
-
PTZ turn to at specified preset at the specified speed.
- $camera_operation_speed
-
Perform camera operation at the specified speed:
- $camera_preset_id
-
Move camera to specfied camera preset, >= IPCamera::Reolink::PTZ_PresetMin, <= IPCamera::Reolink::PTZ_PresetMax.
Used only for IPCamera::Reolink::PTZ_ToPos camera operation.
GetZoomFocus($camera_channel)
Return camera current Zoom and Focus values.
- $camera_channel
-
Perform camera operation on specified camera channel:
- return
-
Returns undef if the GetZoomFocus function failed.
Returns $zoom_focus_r hash reference to Zoom/Focus information if successful, fields most likely subject to change (typical values in parenthesis):
- $zoom_focus_r->{channel} (0)
-
Camera channel.
- $zoom_focus_r->{focus}->{pos} (23)
-
Current camera focus value in the range IPCamera::Reolink::ZF_FocusPosMin, IPCamera::Reolink::ZF_FocusPosMax.
- $zoom_focus_r->{zoom}->{pos} (0)
-
Current camera zoom value in the range IPCamera::Reolink::ZF_ZoomPosMin, IPCamera::Reolink::ZF_ZoomPosMax.
StartZoomFocus($camera_channel, $camera_operation, $camera_zoom_pos|$camera_focus_pos)
Set camera current Zoom or Focus value.
Note that the current version of the firmware on the authors camera (Firmware Version v3.1.0.2347_23061923_v1.0.0.93) requires a Login() using admin credentials to use this function. According to Reolink this may be fixed in a future firmware version.
If in doubt, set $DEBUG to 1 and if you see a log message of the form:
Tue Dec 19 18:17:07 2023: debug: IPCamera::Reolink::_sendCameraCommand(): command 'StartZoomFocus' token '5b34aab0bb481ba' request '[{ action => 0, cmd => "StartZoomFocus", param => { ZoomFocus => { channel => 0, op => "ZoomPos", pos => 1 } } }]' response '[{ cmd => "StartZoomFocus", code => 1, error => { detail => "ability error", rspCode => -26 } }]' time 0.0480499267578125 seconds
then you need to use admin credentials to use this function.
- return
-
Returns 1 if StartZoomFocus() succeeded else 0 (zero) on failure.
- $camera_channel
-
Perform camera operation on specified camera channel.
- $camera_operation
-
Camera operation to perform.
GetOsd($camera_channel)
Return camera current, range and inital On Screen Display (OSD) values.
- $camera_channel
-
Perform camera operation on specified camera channel.
- return
-
Returns (undef, undef, undef) if the GetOsd function failed or ($osd_value_r, $osd_range_r, $osd_initial_r) on success, hash references to OSD current value, range and initial values information if successful, fields most likely subject to change (typical values in parenthesis):
- $osd_value_r
-
Hash reference to current camera OSD values.
- $osd_value_r->{Osd}
-
Current camera OSD values.
- $osd_value_r->{Osd}->{bgcolor} (0/1)
-
Current camera OSD background color disabled (0) or enabled (1).
- $osd_value_r->{Osd}->{channel} (0)
- $osd_value_r->{Osd}->{osdChannel}
-
Current OSD values for specified camera channel.
- $osd_value_r->{Osd}->{osdTime}
-
Current OSD time display values for specified camera channel.
- $osd_range_r
-
Hash reference to camera OSD value ranges.
- TBD
- $osd_initial_r
-
Hash reference to camera OSD initial values.
- TBD
SetOsd($camera_channel, $enableChannel, $channelName, $channelPos, $enableTime, $timePos)
Set camera On Screen Display (OSD) values.
Note that the current version of the firmware on the authors camera (Firmware Version v3.1.0.2347_23061923_v1.0.0.93) requires a Login() using admin credentials to use this function.
- return
-
Returns 1 if SetOsd() succeeded else 0 (zero) on failure.
- $camera_channel
-
Perform camera operation on specified camera channel.
- $enableChannel (0/1)
-
1 to enable display of channelName else 0.
- $channelName ("rlc-823a-16x")
-
Channel OSD text to display
- $channelPos (IPCamera::Reolink::OSD_UpperLeft)
-
Channel OSD text position:
- IPCamera::Reolink::OSD_UpperLeft
-
OSD position "Upper Left"
- IPCamera::Reolink::OSD_TopCenter
-
OSD position "Top Center"
- IPCamera::Reolink::OSD_UpperRight
-
OSD position "Upper Right"
- IPCamera::Reolink::OSD_LowerLeft
-
OSD position "Lower Left"
- IPCamera::Reolink::OSD_BottomCenter
-
OSD position "Bottom Center"
- IPCamera::Reolink::OSD_LowerRight
-
OSD position "Lower Right"
- $enableTime
-
1 to enable display of date/time else 0.
- $timePos ("Upper Left")
-
Date/Time OSD text position:
- IPCamera::Reolink::OSD_UpperLeft
-
OSD position "Upper Left"
- IPCamera::Reolink::OSD_TopCenter
-
OSD position "Top Center"
- IPCamera::Reolink::OSD_UpperRight
-
OSD position "Upper Right"
- IPCamera::Reolink::OSD_LowerLeft
-
OSD position "Lower Left"
- IPCamera::Reolink::OSD_BottomCenter
-
OSD position "Bottom Center"
- IPCamera::Reolink::OSD_LowerRight
-
OSD position "Lower Right"
GetPtzPreset($camera_channel)
Return camera Ptz Presets.
- $camera_channel
-
Perform camera operation on specified camera channel.
- return
-
Returns (undef, undef, undef) if the GetPtzPreset() function failed or ($ptzpreset_value_r, $ptzpreset_range_r, $ptzpreset_initial_r) on success, hash references to PTZ Presets current value, range and initial values information if successful, fields most likely subject to change (typical values in parenthesis):
- $ptzpreset_value_r
-
Hash reference to camera PTZ Preset current values.
- $ptzpreset_value_r->{PtzPreset}
-
List/array of current presets.
- $ptzpreset_value_r->{PtzPreset}->{channel}
-
The camera channel as passed into GetPtzPreset() via $camera_channel.
- $ptzpreset_value_r->{PtzPreset}->{enable}
-
Boolean, true/1 if the preset is enabled, false/0 if disabled.
- $ptzpreset_value_r->{PtzPreset}->{id}
-
Integer preset id, 0 <= id <= 63.
Passed to PtzCtrl() via $preset_id.
- $ptzpreset_value_r->{PtzPreset}->{imgName}
-
Preset image name.
- $ptzpreset_value_r->{PtzPreset}->{name}
-
Preset name.
- $ptzpreset_range_r
-
Hash reference to camera PTZ Preset ranges.
- $ptzpreset_initial_r
-
Hash reference to camera PTZ Preset initial values.
Snap($camera_channel)
Return camera snapshot.
- $camera_channel
-
Perform camera operation on specified camera channel.
- return
-
Returns raw/binary snapshot data in JPG format or undef if the Snap() function failed.
Reboot()
Reboot the camera, on successful return must reestablish the IPCamera::Reolink session.
- return
-
Returns 1 if the camera is rebooted else 0.
Upon successful return the connection to the camera is lost and new session must be established.
AudioAlarmPlay($camera_channel, $manual_switch, $num_times, $alarm_mode)
Play audio alarm.
- $camera_channel
-
Perform camera operation on specified camera channel.
- $manual_switch
-
if $alarm_mode is AAP_AlarmModeManual then set tp 1 to play alarm or 0 to stop alarm.
- $num_times
-
Number of times to play audio alarm, > 0.
- $alarm_mode
-
IPCamera::Reolink::AudioAlarmPlay() alarm_mode values.
- AAP_AlarmModeTimes
-
Play specified # of times.
- AAP_AlarmModeManual
-
Play continuously until next AudioAlarmPlay command.
- return
-
Returns 1 if audio alarm played else 0.
TODO
Implement REST via HTTPS.
Camera seems to "forget" existing REST/HTTP(S) session after period of inactivity.
AUTHOR
Stephen Oberski, <cpan at cargocult.ca>
BUGS
Please report any bugs or feature requests to bug-ipcamera-reolink at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=IPCamera-Reolink. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc IPCamera::ReolinkYou can also look for information at:
RT: CPAN's request tracker (report bugs here)
CPAN Ratings
Search CPAN
LICENSE AND COPYRIGHT
This software is Copyright (c) 2024 by Stephen Oberski.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)