Overview
How To Interface with edelkrone SDK
edelkrone SDK application runs in the background of your computer and translates API commands to the underlying hardware and vice versa. If your programming language or software environment can send and receive HTTP based API commands, you can interface with your edelkrone motion control system(s) through edelkrone SDK using the edelkrone Link Adapter.
You can find summary about various capabilities of edelkrone SDK below. Please check rest of the documentation for more information like commands, response format etc.
User Manual Video
You can watch the edelkrone SDK's user manual video from the following link: http://edel.kr/sdkUm
Periodic Status Update
- You can find the current status of the device, encoder readings, battery level of the units, which axes are supported in the current bundle, which keypose slots are filled etc. information inside this update.
- You need to ask for this manually at regular intervals.
- Status update response returns everything you need in a single JSON package.
- See detailed command structure documentation page for the contents of this periodic update.
- Asking for status will return last updated status of the device regardless of its changes.
- If you want to be sure that status has changed, you can use the TimestampEpoch field value inside the result.
- Periodic update have special URL /bundle/{linkID}/status and you can query a status by sending an empty payload to that URL.
High Level Motion Control Methods
Joystick Move
- You can control Pan / Tilt / Slide axes of your edelkrone motion control system(s) with edelkrone SDK by sending a speed setpoint for each axes seperately in a single command.
- Speed setpoint range is between [-1.0, 1.0]. Speed of each axes is normalised to this range internally
- This method can be useful for coarse positioning of the system with joystick like interface.
- In order for system to move in this mode, you must send periodic updates. If you stop sending a joystick move command, system stops moving after around 1 second.
- This is implemented as a small safety feature.
- Also, this interface has internal "speed ramping" when you send a new speed command.
- Internal speed setpoint changes gradually to give smoother effect.
- Related command(s):
- joystickMove
Focus Move
- Focus axis has different manual control interface than the Pan / Tilt / Slide axes because it requires a finer adjustment capability.
- In this command set, you send deltaEnc information to indicate how much you want the focus motor to move from its current position.
- deltaEnc is unitless and represents raw encoder amount you want to move. Can be negative / positive.
- This method can be useful for controlling the focus motor with a jogwheel alike interface.
- Related command(s):
- focusManualMove
Keypose Move
General Information
- With keypose commands, you can store multiple axis values in a single setpoint group called keyposes and recall them with specific speed and acceleration.
- Motion planning and control are handled inside the motion control system firmware.
- Whole motion control system moves in sync. All axes start and finish the motion at the same time.
- There are upto 6 seperate keypose slots for each motion control system bundle.
- You can either move to a specific keypose slot from your current position and stop after you move there, or you can loop between two keyposes.
Store Current Pose inside a Keypose Slot
- After positioning the whole motion control system to a desired pose by hand or joystick interface, you can store the information about current pose inside a keypose slot using edelkrone SDK.
- Related command(s):
- keyposeStoreCurrentPose
Store Specific Encoder Values inside a Keypose Slot
- You can fill a keypose slot by entering specific encoder values.
- Slide axis unit: centimeters
- Pan / Tilt axis unit: degrees
- Focus unit: unitless (raw encoder values)
- This can be useful when moving the motion control system to a predefined location algorithmically.
- Calibration can be important in this method since you may or may not depend on the power up state of the encoder readings. See related information for calibration if needed.
- Related command(s):
- keyposeStoreWithNumericData
Read Keypose Slot Internal Encoder Values
- You can query internal encoder values of a previously stored keypose slot.
- Related command(s):
- keyposeReadNumericValues
Move to a Keypose Slot with Speed Argument
- You can tell which keypose slot you want to move towards by its index.
- Speed argument is ranging from 0.0 to 1.0
- Speed is normalised based on current bundle.
- Acceleration is ranging from 0.0 to 1.0
- 0.0 being the most immediate start / stop
- 1.0 being the most gradual start / stop
- Related command(s):
- keyposeMoveFixedSpeed
- keyposeLoopFixedSpeed
Move to a Keypose Slot with Duration Argument
- You can tell which keypose slot you want to move towards by its index.
- Duration argument is in seconds.
- Acceleration is ranging from 0.0 to 1.0
- 0.0 being the most immediate start / stop
- 1.0 being the most gradual start / stop.
- Critical Note:
- With this type of fixed duration command, our motion control systems can't guarantee that the motion will be completed with the given duration, if the given duration is shorter than what it can be achieved with %100 speed with given acceleration value.
- If the given duration is shorter than what it can be achieved with %100 speed, system moves with %100 speed with the given acceleration.
- You can check the actual motion duration information inside the periodic status data structure after motion is started.
- Related command(s):
- keyposeMoveFixedDuration
- keyposeLoopFixedDuration
Low Level Motion Control Methods
Real Time Move
- You can use this method to tell your edelkrone motion control bundle to move to a particular position with dynamic setpoints along the way.
- This command can be used to send and playback a precomputed motion profile data to real motion control system in real time.
- You must create a wired setup to facilitate this function in your application. Wireless setups are not that deterministic enough to send continuous setpoints with down to 16ms resolution.
- This is not a 'set it and forget it' type command.
- If you created your arbitrary motion curve profile inside your application with 16ms (60FPS) resolution, you must send periodic updates from your application with 16ms periods in real life as well.
- You can not send a complete motion profile at once and expect your bundle to execute it.
- You must send each setpoint group inside the complete motion profile one by one when time comes.
- You supply position arguments for each axis and motion duration for step in seconds in a single command.
- Your motion control system(s) will calculate neccessary speed setpoints for it to move to the desired setpoint group inside their firmware.
- Try to keep your motion profile in trapezoidal or s-curve like shape with minimum jerk and sudden acceleration / speed changes for the best performance.
- Motion duration for each step must be the same throughout the whole motion profile for the best performance.
- Related command(s):
- realTimeMoveFixedDuration
Pairing & Connecting
- edelkrone SDK gives you full control of pairing a single or multiple edelkrone motion control systems into a bundle connected via wireless or wired interfaces.
- After creating a bundle, you can control motion in the systems and receive periodic response from them using API commands.
- If you don't want to implement the whole pairing system inside your application, you can do a hybrid approach.
- You can pair your edelkrone motion control system(s) to your edelkrone Link Adapter(s) via the edelkrone Web App.
- After pairing with the edelkrone Web App, you can copy and paste the linkID information to your own software environment and you can interface with your motion control system(s) with minimal effort.
- linkID information is globally unique for each edelkrone Link Adapter hardware and it doesn't change after power cycle.
- If you really want to implement whole pairing system inside your own custom software, you can do that as well.
- Each edelkrone Link Adapter can be connected to a single bundle at a given time. You need to disconnect from a specific bundle before trying to connected to another one. (See disconnect command)
Wireless Pairing
- Wireless pairing starts with a discovery. (See wirelessPairingScanStart command)
- Continue to scan the environment for at least couple of seconds.
- While scanning the environment, you can ask for the scan results. (See wirelessPairingScanResults command)
- Scan result tells us which devices your edelkrone Link Adapter found currently.
- Wireless devices are referred by their MAC addresses which can be found inside the scan results for each device.
- MAC addresses are unique to the devices and doesn't change with power cycle.
Create a new bundle and connect
- You can initiate a bundling operation by sending the MAC address of the motion control system(s) you want to connect with edelkrone Link Adapter. (See wirelessPairingCreateBundle)
- After initiating the bundling operation, you can check for connection status to see the progress and check if any problem occured. (See wirelessPairingStatus)
Attach yourself to a previously created bundle
- You can attach your edelkrone Link Adapter to a previously created bundle by sending the MAC adress of the main edelkrone motion control system for the particular bundle. (See wirelessPairingAttachToBundle)
- After initiating the attaching operation, you can check for connection status to see the progress and check if any problem occured. (See wirelessPairingStatus)
Wired Pairing (3.5mm Link)
- In trying conditions, where there is environmental interference with wireless connection, compatible edelkrone motion control systems can have a wired connection with cables to ensure optimum and stable connection with the help of the new edelkrone Link Hub.
- edelkrone Link Hub is sold separately to connect the devices with one another.
- Wired Pairing scenario starts with connecting each device to one another using 3.5mm link cables.
- You can't mix and match Wired and Wireless pairing.
- All of the devices either must be paired with each other completely wired or completely wireless.
- After you connect your devices with each other and power up your devices, you can check which devices are visible inside the wired network. (See link2PairingScanResults)
- Make sure the firmware of your motion control system(s) are up to date if you can't see them.
- After initiating the connection trial, you can check for connection status to see the progress and check if any problem occured. (See link2PairingStatus)
Calibration
- See calibrate command documentation for detailed interface information for each calibration procedure
Slide Module v2 / v3
- You can define whether SliderPLUS & Slide Module is mounted on a tripod or not.
- SliderPLUS goes 2x amount when mounted on a tripod and it effects internal encoder to real value conversions.
- You can tell which way (left or right) you mounted the Slide Module to the SliderPLUS with respect to default camera direction.
- This effects the sign of internal encoder calculations
Figure1: Right mounting
Figure2: Left mounting
- After the calibration, Slide Module encoder resets to 0 cm.
HeadPLUS v1 / PRO, HeadPLUS v2 / PRO, HeadONE (dual)
- When you send a calibration command
- Pan encoder resets to: 90.0 degrees
- Tilt encoder resets to: 0.0 degrees
HeadONE (single), Pan PRO
- When you send a calibration command
- Pan encoder resets to: 90.0 degrees
FocusPLUS PRO
- If you don't initiate a calibration with FocusPLUS PRO, motor tries to move freely without any limits.
- When you initiate a calibration with FocusPLUS PRO,
- Tries to find two endpoints of your lens.
- Resets its encoder value to zero after the second stop.
- Limits the focus motor motion range according to the endpoints of your lens.
JibONE
- You can calibrate JibONE by sending jibLength and rodLength parameters to edelkrone SDK if you want more realistic position information.
- jibLength and rodLength values are referred by the notches on JibONE engravings.
Figure4: jibLength and rodLength notch locations
- After calibration, JibONE encoder resets to zero.
Figure3: Lock the JibONE at the middle position to make an accurate calibration.
- You can refer to the procedure in edelkrone Web App for the details.
- By default JibONE assumes jibLength=27 and rodLength=4
SliderONE v2, SliderONE PRO v2
- These products implements an auto calibration procedure after powering up.
DollyONE, DollyPLUS, DollyPLUS PRO
- These products don't have a calibration procedure.
Axis Naming Convention
- In this chapter, you can find the naming convention we use inside edelkrone SDK for our motion control systems in different scenarios.
- These names are used when reading encoder values, moving the motor via joystick interface, moving the motors via keypose interface etc.
headPan
- Refers to pan axis of HeadPLUS series products.
- Refers to pan axis of setups with single or dual HeadONE.
- Refers to pan axis of Pan PRO.
- Exception: If JibONE is paired with Pan PRO as Jib Panning mode in a particular bundle, Pan PRO readings doesn't get published as headPan. See jibPlusPan axis information below.
- Relevant products:
- HeadPLUS v1, HeadPLUS v1 PRO
- HeadPLUS v2, HeadPLUS v2 PRO
- HeadONE
- Pan PRO
headTilt
- Refers to tilt axis of HeadPLUS series products.
- Refers to tilt axis of setups with single or dual HeadONE.
- Relevant products:
- HeadPLUS v1, HeadPLUS v1 PRO
- HeadPLUS v2, HeadPLUS v2 PRO
- HeadONE
slide
- Refers to linear distance traveled with Slide Module, SliderONE and Dolly series products.
- Refers to the approximate linear distance traveled with JibONE
- Exception: If JibONE is paired with Pan PRO as Jib Panning mode in a particular bundle, JibONE readings dont't get published as slide. See jibPlusTilt axis information below.
- Relevant products:
- Slide Module v2, Slide Module v3
- SliderONE v2, SliderONE PRO v2
- DollyONE, DollyPLUS, DollyPLUS PRO
focus
- Refers to focus motor encoder reading in raw form for FocusPLUS PRO and Focus Module products.
- Relevant products:
- FocusPLUS PRO
- Focus Module
jibPlusPan
- When JibONE is paired with Pan PRO as Jib Panning mode in a particular bundle, Pan PRO readings are referred as jibPlusPan
jibPlusTilt
- When JibONE is paired with Pan PRO as Jib Panning mode in a particular bundle, JibONE readings are referred as jibPlusTilt