View source for AXIOM Beta Firmware Version 2.0

==Prepare Micro SD Card==
# Get a new Micro SD card (4GB is enough, bigger is fine as well, but the partitions are not yet automatically resized when a bigger SD card is detected).
# Acquire the latest automatically built firmware image from: https://github.com/apertus-open-source-cinema/axiom-beta-firmware/releases - don't be alarmed by the name "Unstable Development Snapshot" it just means the firmware has been automatically built without human interaction.
# Download, install and start Etcher: https://www.balena.io/etcher/
# Flash the acquired image to a new Micro SD card with Etcher (we highly recommend not overwriting the Micro SD card you currently use in your AXIOM Beta).
# After flashing put the Micro SD card into the AXIOM Beta Microzed SD card slot and power up the Beta.

Optionally after booting the AXIOM Beta for the first time and logging in you can resize the partition to fill the entire Micro SD card:

run as root:
 axiom_grow_fs.sh

For a full guide about firmware flashing/backup see: [[AXIOM_Beta/Firmware_Flashing | Firmware Flashing]]

==General Notes==
This new firmware is still in development so expect issues and bugs. 

This is the list of current issues/bugs: https://github.com/apertus-open-source-cinema/axiom-beta-firmware/issues

If you find a new bug or have ideas for improvement please add it as github issue (please first check it has not been reported yet).

Default user is '''operator''' and password: '''axiom'''

Administrator user is '''root''' and password: '''axiom'''

Sudo or logging in as root is required to change system/camera settings (like running the various scripts)

==Hostname==

When connecting to the camera via Wifi the hostname is automatically set to '''axiom.camera'''.

This means you can use '''axiom.camera''' instead of the IP in your browser to access the WebUi or through ssh:

 <pre>ssh operator@axiom.camera</pre>

 <pre>ssh root@axiom.camera</pre>

==axiom_ prefix==
All camera related programs and scripts are now prefixed with:

<code>axiom_</code> 

so for example to run (Firmware 1.0 command):

<code>set_gain.sh</code> 

with Firmware 2.0 you now run: 

<code>axiom_set_gain.sh</code>

==script/binary location==
All scripts/binaries are now executable from anywhere. 

To find their actual location you can use: 

<code>which axiom_set_gain.sh</code> 

or if you want to use the script without caring about where its actually stored you can use: 

<code>$(which axiom_start.sh)</code> 

for example to show the content: 

<code>cat $(which axiom_start.sh)</code>.

==Old vs New command names==
{| 
! Old Command (Firmware 1.0)
! New Command (Firmware 2.0)
|-
| <code>kick_manual.sh</code>|| <code>axiom_start.sh</code>
|-
| <code>halt_manual.sh</code>|| <code>axiom_stop.sh</code>
|-
| <code>cmv_snap3</code>|| <code>axiom_snap</code>
|}

Start the continuous image acquisition (HDMI output):

<code>axiom_sequencer_start.sh</code> 


Stop the continuous image acquisition (HDMI output):

<code>axiom_sequencer_stop.sh</code> 

** For example : <code>./cmv_snap3 -e 20ms -z</code> is now done by typing <code>sudo axiom_snap -e 20ms -z</code>
* Image build log is located in each image under: <code>/var/build.log</code> 
* Devicetree source can be found at <code>/boot/devicetree.dts</code>. To recompile it after any changes use <code>dtc -O dtb -o /boot/devicetree.dtb /boot/devicetree.dts</code>
* To interrupt the autoboot from u-boot send <code>Ctrl-C</code> over serial quickly after a boot / reboot (try holding it down)  
* <code>axiom_file_check.sh</code> does an integrity check of /usr, /etc and /opt
* Binaries are linked in: <code>/usr/axiom/bin</code> 
* Scripts are linked in: <code>/usr/axiom/script</code>
* <code>/opt/axiom-firmware</code> contains scripts and binaries
* Every AXIOM Beta currently has the same MAC address - a random one should be generated on the first boot, but this is not implemented yet.
* Second Micro SD card slot is enabled by default.
* Factory Calibration Routines have been forked for firmware 2.0: [[Factory_Calibration_(firmware_2.0)]]


===FPGA Bitstreams===

FPGA bitstreams are located in 

<code>/usr/lib/firmware</code> 

and softlinked to from 

<code>/opt/bitstreams/</code>


*.bit files (from old firmware) need to be converted to *.bin files (for new firmware) with:

<code>/opt/axiom-firmware/makefiles/in_chroot/to_raw_bitstream.py -f input_file.bit output_file.bin</code> 

and copied to 

<code>/lib/firmware</code>


Make sure to load new bitstreams as root:

<code>sudo su</code>

Then:

<code>echo axiom_fpga_main.bin > /sys/class/fpga_manager/fpga0/firmware</code>

and not:

<code>sudo echo axiom_fpga_main.bin > /sys/class/fpga_manager/fpga0/firmware</code> 

or  use:

<code>echo <BITSTREAM_NAME> | sudo tee /sys/class/fpga_manager/fpga0/firmware</code>

'''Further documentation:'''

* https://github.com/apertus-open-source-cinema/axiom-beta-firmware/blob/master/README.md
* https://github.com/apertus-open-source-cinema/axiom-beta-firmware/blob/master/software/scripts/README.md
* [[AXIOM Beta]] main page.

==Capture Still Images==

There is a command-line tool available on the camera called '''axiom_snap''' that allows you to capture still images and takes various parameters. 

Note that the image sensor communication needs to be initiated before you can capture still images with kick_manual.sh (Firmware 1.0) or axiom_start.sh (Firmware 2.0). Trying to capture image or read/write any image sensor registers before initiating the image sensor communication will freeze the camera firmware and require a reboot. 

The still images are captured in a raw image format called [[RAW12]] or raw16 (deprecated - the CMV12000 only provides 12 bit so using raw16 is not recommended) which is basically just raw pixel data dumped into a file plus an optional metadata block containing image sensor configuration (it is recommended to always store the metadata as it can be useful for the DNG conversion with [[raw2dng]] - also its just a tiny amount of data [128x16bit] and might come in handy at a later image processing step.)
Note that axiom_snap cannot be utilized via serial console (minicom, screen, etc.). If you want to write images to your host computer, use SSH connection instead.

===axiom_snap parameters===

The following parameters are available:

  <pre style="white-space: pre-wrap">axiom_snap -h
This is axiom_snap cmv_snap3 V1.11
options are:
-h        print this help message
-8        output 8 bit per pixel
-2        output 12 bit per pixel
-d        dump buffer memory
-b        enable black columns
-p        prime buffer memory
-r        dump sensor registers
-t        enable cmv test pattern
-z        produce no data output
-e <exp>  exposure times
-v <exp>  exposure voltages
-s <num>  shift values by <num>
-S <val>  writer byte strobe
-R <fil>  load sensor registers
</pre>


'''Examples'''

Images can be written directly to the cameras internal micro SD card like this (10 milliseconds exposure time, 12bit, include metadata registers):
 axiom_snap -e 10ms -r -2 > image.raw12

You can also use axiom_snap to change exposure time (to 5 milliseconds in this example) without actually capturing an image, for the that -z parameter is used to not produce any data output:
 axiom_snap -z -e 5ms


That axiom_snap writes data to STDOUT makes it very versatile, we can for example capture images from and to a remote Linux machine connected to the Beta via Ethernet easily (lets assume the AXIOM Betas camera IP is set up as: 192.168.0.9 - SSH access has to be set up for this to work with a keypair - this does not work over the serial/USB console)
 ssh operator@192.168.0.9 "axiom_snap -2 -r -e 10ms" > snap.raw12

To pipe the data into a file and display it at the same time with imagemagick on a remote machine:
 ssh operator@192.168.0.9 "axiom_snap -2 -r -e 10ms" | tee snap.raw12 | display -size 4096x3072 -depth 12 gray:-

Use imagemagick (tested with Version 6 and 7) to convert raw12 file into a color preview image:
 cat test.raw12 | convert \( -size 4096x3072 -depth 12 gray:- \) \( -clone 0 -roll -1-1 \) \( -clone 0 -roll -1+0 \) \( -clone 0 -roll +0-1 \) -sample 2048x1536 \( -clone 2,3 -average \) -delete 2,3 -swap 0,2 -combine test_color.png

Use imagemagick (tested with Version 6 and 7) to convert raw12 file into a color preview image (swapped lines from a bug in an earlier version of cmv_snap3):
 cat test.raw12 | convert \( -size 4096x3072 -depth 12 gray:- \) \( -clone 0 -roll -1-1 \) \( -clone 0 -roll -1+0 \) \( -clone 0 -roll +0-1 \) -sample 2048x1536 \( -clone 2,3 -average \) -delete 2,3 +swap -combine test_color.png

With raw2dng compiled inside the camera you can capture images directly to DNG, without saving the raw12:

 axiom_snap -2 -b -r -e 10ms | raw2dng snap.DNG

'''Note:''' Supplying exposure time as parameter is required otherwise axiom_snap will not capture an image.
The exposure time can be supplied in "s" (seconds), "ms" (milliseconds), "us" (microseconds) and "ns" (nanoseconds). Decimal values also work (eg. "15.5ms").