apex

KO | EN

gitlite — search

#python #hacktoberfest #typescript #llm #go #rust #linux #docker #macos #nodejs #vue #openai #mcp #open-source

(★ 11)

Take Deep Control of your JVC projector plus Optimize the JVC + HD Fury HDR experience.

apex Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Apex

Apex is a powerful tool to control your JVC projector and other devices.   Apex offers several great features.

Apex started life as a tool to deeply control JVC projectors with a focus on assisting with the challenges of early HDR support in JVC projectors.   While that need has gone away, Apex is still extremely useful because it allows robust control of the JVC projector.

1. Apex enables reliable and robust control of the JVC projector.  JVC projectors are known for ignoring commands "when they are busy."  If you tell Apex, for example, to power off the JVC while it's "attempting to sync to a new video format", Apex will ensure the projector powers off.   Apex is the opposite of a "toss the command to the projector and hope it does it" solution.
1. Apex allows deep control of the JVC using both network connectivity and IR.   You can tell the projector to do any command it supports.
1. Apex allows deep control of other devices, including ones supporting Onkyo's ISCP, HDFury's IP protocol and the very powerful ability to execute shell commands

In the past Apex would have also highlighted "Apex optimizes the JVC + HD Fury HDR experience."

Keep in mind that Apex does a lot of things, but if you only want to use it to robustly control your JVC projector, it does that extremely well and other features can be ignored.

# What's New?

The latest release has the following changes.

1. Support for newer JVC projectors requiring a SHA hash of a password
1. Small internal improvements

# Apex Deep Control

Apex allows commands from JVC's "External Control Command Communication Specification" to be performed by network commands or IR keypress.
Unlike using the projector's IR remote, or an automation solution like Harmony, Apex verifies that commands are actually performed.  With
Apex, for example, you don't need to hard code length (40 second?) delays because the JVC is switching inputs or is powering on.   Apex will
make sure the command is performed when the JVC is paying attention.

Deep control allows the following types of settings to be adjusted

* Lens Memory
* Aperture
* Contrast
* Brightness
* Gamma table
* Mask
* Lamp Power
* Etc.

# Apex Profiles

Everything (almost) in Apex is a profile.   A profile is a named collection of JVC control commands.  A profile can have 1 command or many commands.
Place whatever commands are needed to configure your JVC for your specific situation.  For example, you could create a profile called 
"cinemascope" which activates the appropriate picture mode, lens zoom, lens aperture and mask settings.  You can be confident that all the commands
in your profile will be performed.

In addition to custom profiles, Apex has several "core" profiles that are used with the HDR + HDFury integration.   When the HD Fury devices
tells Apex (via serial) to activate a specific picture mode, Apex activates a core profile named similar to the picture mode.  For example,
if HD Fury says to activate picture mode User 2 then Apex will enable profile "_APEX_PMUser2".  The default setting for profile "_APEX_PMUser2"
is to use the Apex Optimized Picture Mode algorithm for User 2.  However, you can add any commands you want to the core profiles.

Apex allows external devices to activate profiles using network communication.   Additionally, Apex allows profiles to be activated based on
IR commands.

## Operation Targets

This release of Apex allows control of devices beyond the JVC projector!  While Apex has always received data via serial
from an HDFury Vertex 2 and controlled a JVC projector by IP, this version allows control of additional devices.   Specifically:

1. Apex can now send commands to the HD Fury Vertex 2 (and probably other HD Fury devices) via IP
1. Apex can now send commands to Onkyo receivers supporting ISCP (their control protocol)

In addition to controlling new devices by IP, Apex also now supports executing arbitrary shell commands.

The above functionality is implemented in a "plugin" like manner which should allow "easy" support for new devices in the future.

This new functionality is implemented in a manner consistent with existing Apex operations.   Each operation now supports a new
"target" parameter.   Currently the supported targets are

1. jvc_pj
1. hdfury_generic
1. onkyo_iscp
1. apex_shell

As an example of using "target", the following operation changes an Onkyo receiver's volume

```
  - op: raw
    target: onkyo_iscp
    cmd: MVL
    data: '3C'
```

For backward compatibility, if the target is not specified then it is assumed to be "jvc_pj"

# Apex Setup

Apex is written in Python 3.  There are a million ways to run python code.  Below is one simple approach.

Note: the following instructions assume Apex is running with a HDFury device and a USB serial port.
If you want to run Apex without a USB serial port (and therefore not use any of the HDFury optimizations),
you need to comment out the "hdfury" line in the apex.yaml file.

1. Create a directory somewhere called apex
1. Retrieve Apex from the Repo
1. Install the requirements using "pip3 install -r requirements.txt"
1. Configure Apex with the IP address of your JVC and the device name of your serial port.  In the apex.yaml file, inside the "jvc_pj" object, change "ip" parameter to be the IP of the JVC projector and within the "hdfury_serial" change "device" to be the serial device name of the HDFury device.
1. Configure Apex for network control.  In the apex.yaml file, change "netcontrolport" to the port that Apex listens on for external commands.  Also change 
"netcontrolsecret" to a secret value for your specific setup.
1. If your JVC's network control has a password set, set the "password" field under "jvc_pj" to that password, in plain text.  Apex computes the required SHA-256 hash itself:

```
jvc_pj:
  ip: '192.168.10.202'
  port: 20554
  password: '1234567890'
```

If "password" is omitted, Apex connects exactly as before (no authentication).
1. Eventually you'll want to have Apex start automatically, but to get started you can simply use "python3 apex.py"

# HDFury Setup

Note: You don't need an HDFury / Vertex2-like device to use Apex.  However, if you have one, Apex will control it!

The HDFury device, such as the Vertex 2, requires the following configuration:

If you don't know how the serial ports are named on the device running Apex, you can launch Apex with the flag "--showserialports" and it will output the potential serial ports

1. Make sure the HDFury device's serial output is connected to the device running Apex.  If you use a serial extension cable, ensure it is a straight serial cable (NOT a NULL modem cable).  
1. Set the Macro "Sync Delay (secs)" to be 1.  I wish it could be set to 0, but the HDFury does not work correctly when 0 is specified.
1. Make sure the Macro "Send on every sync" is checked. 
1. Don't forget to press the "Send Macro Values" button on the bottom of the screen.   This is required for the HDFury device to save the new settings.

# Onkyo ISCP Command Target Setup

Note: You don't need an Onkyo AVR to use Apex.   However, if you have one, Apex will control it.

If you want to use Apex to control an Onkyo ISCP device, you must provide Apex with the IP address of your Onkyo device.  Under the onkyo_iscp object,
update the ip field to contain the device's IP address.

```
onkyo_iscp:
  ip: '192.168.10.165'
  port: 60128
```

# HDFury Generic IP Setup

If you want to use Apex to control an HDFury Generic IP device, you must provide Apex with the IP address of your HDFury device.   Under the hdfury_generic object,
update the ip field to contain the device's IP address

```
hdfury_generic:
  ip: 'vertex2-28.local'
  port: 2220
```

# Profile Details

Profiles are stored in the apex.yaml file.  All profiles, whether custom or core, exist under the "profiles" entry.  Below is an example.

```
profiles:
# Apex Core Profiles
# Profile names beginning with _APEX_ have specific meaning and should not be removed
# However, you are more than welcome to change the contents of the profile

_APEX_PMFilm:
  - op: apex-pm
    data: '00'

_APEX_PMCinema:
  - op: apex-pm
    data: '01'
```

All profiles follow a standard format.  First there is the profile name.   This is followed by one or more operations ("op") and respective operation
parameters.

By default, Apex will not send profile operations to the JVC when the JVC is powered off.   This is because the JVC protocol is rather basic and does not
allow Apex to know if the JVC just missed a command or is intentionally ignoring it. This intelligent operation removes many situations where the JVC will
likely ignore commands, allowing Apex to avoid retransmission and unwanted timeouts.  The optional parameter "requirePowerOn" can be set to False to change
the default behavior.

The profile operations are described below.

## "apex-pm" operation
This is Apex's special sauce state machine that optimizes picture mode selection.  If you want to select a picture mode, you
should use apex-pm instead of alternative methods.   When using apex-pm, a "data" field must exist.  This indicates which picture mode
to activate.   The optional parameter "requirePowerOn" is supported.  See the default apex.yaml file for the mapping of the data
parameter to picture mode names.

```
  _APEX_PMFilm:
  # Activate picture mode Film
  - op: apex-pm
    data: '00'
```

The apex-pm operation also supports a field called "onNoChange", which is optional.   If this field is specified and the requested picture mode requires no change to the projector (because the projector is already in that mode), Apex will skip all operations that follow until an "apex-mark" operation is found with a matching string.

## "apex-mark" operation
The mark operation currently only works in conjunction with the apex-pm operation.   "apex-mark" specifies a "mark" (or location) in the profile.   This allows Apex to skip all operations prior to the mark.   When using apex-mark, a "data" field must exist.   This contains a string that uniquely identifies the mark.

The following is an example use of apex-mark in a custom picture mode profile.

```
  _APEX_PMUser1:
  - op: apex-pm
    data: '0C'
    onNoChange: 'Mark_Jump'
  - op: apex-delay
    data: '4000'
  - op: raw
    cmd: PMDI
    data: '0'
  - op: raw
    cmd: PMLA
    numeric: -15
  - op: apex-mark
    data: 'Mark_Jump'
```

This example says "if there is no change needed when selecting picture mode "User1", jump to the mark with the name "Mark_Jump" (skipping all the operations in-between).  However, if the JVC was in a picture mode other than "User1", all operations would be performed (delaying 4s, disabling the dynamic iris, setting the iris to -15).

## "apex-hdmi" operation
Special sauce?   Yes.   Using the operation apex-hdmi avoids activating a HDMI input if it's already active.   The data parameter 
is '1' for HDMI 1 and '2' for HDMI2.  The optional parameter "requirePowerOn" is supported.

```
  profileHDMI1:
  # HDMI1
  - op: apex-hdmi
    data: '1'
```

## "apex-power" operation
More Apex special sauce, the apex-power operation not only tells the JVC to turn on or off, but ensures that it does turn on or off.
Using the raw commands you may find the JVC says it turned off but actually does not.   Because of this, it is recommended that
apex-power be used for all power on/off operations.   When using apex-power, a "data" field must exist.   This indicates whether to 
power on or power off the JVC.  The optional parameter "requirePowerOn" is supported.

```
  - op: apex-power 
  # Power On
    data: 'on'
    requirePowerOn: False

profilePowerOff:
  # Power Off
  - op: apex-power 
    data: 'off'
```

## "apex-delay" operation
This is for use under special circumstances.  The apex-delay operation causes Apex to wait (aka delay) the specified amount of time before
processing the next operation in the profile.  While this can be used however desired, it was added because the JVC responds that it has
completed restoring lens memory before the lens has reached the final spot.

When using apex-delay, a "data" field must exist.   This indicates the number of milliseconds to delay.
The optional parameter "requirePowerOn" is supported.

```
  # delay 10 seconds
  - op: apex-delay
    data: '10000'
```

## "apex-hdfurymode" operation
The apex-hdfurymode operation tells Apex whether it should "follow" or "ignore" HDR modes specified by an HD Fury device.
When set to "follow", Apex will act upon HD Fury HDR modes and when set to "ignore", Apex will ignore HD Fury HDR modes.
When using apex-hdfurymode, a "data" field must exist.  It must be set to either "follow" or "ignore".

The optional parameter "requirePowerOn" is supported.  However, the default is set to False (meaning this command is 
processed regardless of the JVC power state).

```
  # Apex will follow the HDR info provided from HD Fury
  - op: apex-hdfurymode
    data: 'follow'
```
```
  # Apex will ignore the HDR info provided from HD Fury
  - op: apex-hdfurymode
    data: 'ignore'
```

## "apex-ongammad" operation

Note: This was never used by any anyone, including me, and will likely be removed in a future version.

The apex-ongammad operation tells Apex to watch the JVC's gamma table and, should Gamma D be detected,
perform the commands specified in a profile.   The profile is specified in the operation's data
parameter.   "On Gamma D" detection defaults to off and is enabled by performing the apex-ongammad operation
with a profile.

```
  # this example shows enabling the On Gamma D functionality and performing profile "profileTestSelectGammaCustom1" when detected
  - op: apex-ongammad
    data: 'profileTestSelectGammaCustom1'
```

```
  # this example shows disabling the On Gamma D functionality
  - op: apex-ongammad
    data: ''
```

If the apex-ongammad operation is used, it is very important that the specified profile performs
actions that cause the gamma table to change.   If not, Apex will keep noticing Gamma D and keep
performing the operations in the profile over and over.

## "raw" operation
The raw operation mode allows any JVC control command to be executed.   Raw requires a "cmd" field and then either a "data" field or
a numeric field.   Either one can be used, the two options exist to make your life easier.  If numeric is specified, Apex takes the
specified signed integer and converts it into the JVC control format.  Alternatively, you can use the "data" field.  This field allows ASCII
data to be specified. The optional parameter "requirePowerOn" is supported.

The raw operation also supports an optional "timeout" parameter.  This parameter should not be used unless there is a very specific reason.
When not specified, Apex uses the default Apex algorithm to optimize the JVC's behavior.   However, if there's a unique scenario where 
the JVC performs poorly with this default behavior, a timeout (in milliseconds) can be specified.  When the timeout is specified, Apex will stop attempting to have the JVC
perform the specified command after the specified timeout's duration.   Keep in mind that while a short timeout may seem appropriate at first,
the JVC can be unresponsive for 20+ seconds in some conditions.

Here is an example of a raw command with numeric

```
  # set the aperture to -10
  - op: raw
    cmd: PMLA
    numeric: -10
```

Here is an example of a raw command with data

```
  # Gamma Custom 2
  - op: raw
    cmd: PMGT
    data: '5'
```

Here is the same example as above but with the (not recommended for casual use) timeout parameter.   The timeout
is set to 5000 ms (or 5 seconds)

```
  # Gamma Custom 2
  - op: raw
    cmd: PMGT
    data: '5'
    timeout: 5000
```

## "rccode" operation
This stands for remote control code.  This operation allows buttons from the remote to be simulated.  Using rccode is
not recommended because the JVC control protocol treats these exactly like IR commands, which means they might be missed or
ignored.  The rccode operation is included only for completeness.  The optional parameter "requirePowerOn" is supported.

Here is an example rccode that displays (or removes) the "Menu"

```
  # RC code for Menu
  - op: rccode
    data: '732E'
```

Note that many older documents pertaining to remote control code often include only a single hex value, such as 2E.  In most
cases you can make those work by simply adding 73 to the front (resulting in 732E).  The full 4 character code is supported by 
Apex because it allows remote control codes to operate when the JVC is configured for "Code B" (opposed to "Code A") IR codes.
If you want to send "Code B" commands, replace the 73 with 63.

## Onkyo ISCP Command Target

The Onkyo ISCP Command Target supports raw commands.  Below is an example that powers on an Onkyo ISCP device.

```
  profileOnkyoPowerOn:
  - op: raw
    target: onkyo_iscp
    cmd: PWR
    data: '01'
    requirePowerOn: False
```

## HDFury Generic IP Command Target

The HDFury Generic Command Target supports raw commands.  Below is an example that enables splitter mode with input 1 selected.

```
  - op: raw
    target: 'hdfury_generic'
    cmd: set
    data: 'insel 0 4'
    requirePowerOn: False
```

## Apex Shell Command Target

The Apex Shell Command Target supports raw commands.   The cmd field specifies the program to run and the data field specifies any parameters.
Below is an example using python3.7 to run a made up program.

```
  - op: raw
    target: apex_shell
    cmd: '/usr/bin/python3.7m'
    data: 'myOwnStuff.py -myOwnCommand myOwnParameter'
    requirePowerOn: False
```

## Bringing it Together
As stated, profiles can have multiple operations.  Below is an example profile called "profileExample" that combines some of the
operations mentioned above.

```
  profileExample:
    # select film mode
    - op: apex-pm
    data: '00'

# set the aperture to -10
  - op: raw
    cmd: PMLA
    numeric: -10

# Press the Menu button
  - op: rccode
    data: '732E'
```

# Network Control
While any application can support the Apex protocol, Apex comes with a very simple tool to send network commands.
This tool is called apexcmd.py.  Apexcmd tells Apex to enable a specific profile.  You can run apexcmd with or
without a configuration file.

By default, apexcmd looks for the configuration file apexcmd.yaml in the current directory.   This file has the values
for Apex Server IP, Apex port IP and the shared secret.   The name and location of this file can be changed by 
using the --configfile parameter.  It looks like the following

```
#
# Example Apex Command config file
#

ip: 192.168.1.123
port: 12345
secret: secret
```

When using the config file, the --profile parameter specifies the profile to execute.   For example:

```
python3 apexcmd.py --profile profileHDMI1
```

You can override any of the fields in the config with the command line options --ip, --port and --secret.   If
you do not want to use a config file at all, you can specify the --noconfigfile.

# IR Key Support
Apex allows a profile to be activated when an IR Key is received.   Currently Apex supports IR key functionality when
running on Linux systems.   The IR functionality of the system must be setup and operational before Apex can know
about IR keypresses.  This setup is beyond the scope of this document (but perhaps I'll add info later).

The mapping from IR key to profile is done with the apex.yaml file.   The field "keymap" is used.   An example is shown below.

```
keymap:
  KEY_F1: 
    profile: profilePowerOn
  KEY_F2: 
    profile: profilePowerOff
  KEY_1: 
    profile: profileHDMI1
  KEY_2: 
    profile: profileHDMI2
```

In the above example, when Apex receives an IR keypress represented as "KEY_F1", it will activate the profile named "profilePowerOn".  When
Apex receives the IR keypress represented as "KEY_1", Apex will activate the profile named "profileHDMI1".

You can map any supported Linux key code to any defined profile.

## New Configuration File Format

In order to support the target functionality and easily support new targets moving forward, all target
configuration is now placed into a target object.   _This breaks compatibility with the previous configuration 
format._

The old configuration format looked like

```
  jvcip: '192.168.10.202'
  jvcport: 20554
  hdfury: '/dev/ttyUSB0'
  netcontrolport: 12345
  netcontrolsecret: 'secret'
  keydevice: '/dev/input/event0'
```

This now looks like

```
  jvc_pj:
    ip: '192.168.10.202'
    port: 20554

hdfury_serial:
    device: '/dev/ttyUSB0'

netcontrol:
    port: 12345
    secret: 'secret'

keys:
    device: '/dev/input/event0'
```

Using this new configuration format, the new targets are configured using

```
  hdfury_generic:
    ip: 'vertex2-28.local'
    port: 2220

onkyo_iscp:
    ip: '192.168.10.165'
    port: 60128

apex_shell:
    _ignore: True
```

## Second Configuration File Support

With this release, Apex supports 2 configuration files, Config1 and Config2.   Any parameters
placed into Config2 will replace anything that already exists in Config1.  This two configuration
file approach should allow users to keep their customizations in a file separate from the official
Apex release while still using settings or parameters that exist in the default configuration.

In order to use the second configuration file, the new command line parameter "-configfile2" (or "-cf2")
has been added.

# Tips

If you don't know how the serial ports are named on the device running Apex, you can launch Apex with the flag "--showserialports" and it will output the potential serial ports

# Discussion?

Want to discuss Apex?  Check out this [thread on AVSForum](https://www.avsforum.com/threads/apex-—-jvc-rs500-600-hdfury-hdr-macro-optimization.3177726/#post-60365429)

# Older But Still Interesting

## Using Apex Example

A little information about how I use Apex is documented [here](how.md).   It covers the profiles I use to control my JVC, Vertex2 and Onkyo receiver as well
as explaining my use of 2 EDID tables.

## Apex HDR Experience Optimization

The JVC RS500/RS600 projector models have the tech specs to support HDR very well (at least for projectors), but JVC provided a truly terrible HDR implementation. Amazing people on AVS have come up with ways to get HDR working on these projectors.  One part of this requires using an HDFury product, such as the Vertex 2, and connecting it via serial/RS232 to the JVC projector.  The HDFury then sends "macro" commands via RS232 which cause the JVC to select appropriate HDR (or non-HDR) picture mode.

Apex optimizes this step by intelligently working with the JVC projector.  Without Apex, you must select a single default "delay" on the HDFury product.  When the HDFury product sees a content HDR transition, it waits the amount of time specified by this delay, and then sends the "macro".  A delay is often needed because the JVC stops listening to all commands when changing certain modes and this sometimes occurs when HDR content is started or ended.  The JVC may be in the "not listening" state for many seconds, perhaps up to 20.  Because of this, many people set the HDFury delay to 20 seconds.  However, this means that the user must always wait 20 seconds for the correct HDR mode to be selected, even if the JVC is ready to display content immediately or anything faster than 20 seconds.

Apex works intelligently with the JVC and sends the macro command as soon as the JVC is ready to receive the command.   If the JVC is ready after 1 second, the HDR switch occurs after about 1 second.   JVC ready after 5 seconds?  The switch occurs after about 5 seconds.  If it takes a full 20 seconds, the switch will occur at that time.

Apex removes the need to connect a serial cable to the JVC because Apex communicates with the JVC using Internet Protocol.  The HDFury is now connected by serial to the device running Apex.

# Is Apex Right for Me?

Apex may be right for you if...
* You are currently using, or plan to use, a JVC RS500/600 projector with an HDFury device to enable proper HDR?   
* Your current HDFury macros use the JVC picture modes (USER1, USER3, NORMAL, etc.)?
* You prefer to use IP connectivity to your JVC projector rather than running a serial/RS232 cable?
* You are annoyed by HDR modes activating or deactivating with seemingly random delays after starting or stopping content? 
* Your JVC does not reliably turn on or off and you'd like rock solid behavior?
* You are tired of hard coding 40+ second delays into your Harmony scripts in order to get the JVC to switch HDMI inputs
* Your HTPC integration with the JVC is not cutting it and you'd like a robust solution to control the JVC 
* You want to control Onkyo ISCP devices, HDFury Generic IP devices, or just execute arbitrary shell scripts

# Example of Apex's HDR Optimization Value

You use an NVIDIA Shield as a media player and use different applications such as Netflix and Kodi.  
* Play HDR with Netflix
  * Without Apex, when you start HDR content in Netflix, the HDR mode will not activate for about 20 seconds.
  * With Apex, the HDR mode activates almost immediately

* Play HDR with Kodi (w/frame rate matching set to "on start")
  * Without Apex, when you start HDR content, the HDR mode will activate many seconds after the frame rate changes
  * With Apex, the HDR mode activates almost immediately

* Stop HDR content from Kodi
  * Without Apex, Kodi displays its menu and the color intensity is all wrong for close to 20 seconds and then changes
  * With Apex, Kodi displays its menu and the HDR mode turns off almost immediately

Note: There are lots of variables that impact the behavior described above, but the above is representative of what I see.  The non-Apex cases assume 
a HDFury "delay" setting of 20 seconds.

apex

apex Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

apex

apex Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README