diff --git a/PixelatorControllerSettings.md b/PixelatorControllerSettings.md
new file mode 100644
index 0000000..db135f4
--- /dev/null
+++ b/PixelatorControllerSettings.md
@@ -0,0 +1,416 @@
+The first argument passed to PixelatorController start script is the filename
+of the settings file. Some of the settings in that file are filenames
+of other settings files. This article describes these settings files with
+one section per file.
+
+The file format is [JSON](http://www.json.org/)
+
+# Settings 
+
+## Scan Files: Directory 
+Every scan creates a hdf5 file. The directory they are stored in is:
+_base directory/YYYY-mm-dd/_
+
+**NeXusBaseDirectory**::
+- base directory to save scan files
+
+ **NeXusLocalBaseDirectory**::<BR>
+    base directory used when '''Save local''' is active
+
+ **defaultSaveLocal**::<BR>
+    Save local setting on startup. <BR>
+    "yes": use '''NeXusLocalBaseDirectory''' directory <BR>
+    anything else: use '''NeXusBaseDirectory''' directory
+
+Depending on the scan type, the files are archived or not.
+The archived ones are put in that date directory.
+The others in a discard sub directory of the date directory.
+
+ NeXusDiscardSubDirectory::
+    sub directory for files not archived
+
+The '''''ScanType''_Archive_Default''' options define a default archive flag for each scan type.
+They are used when '''''ScanType''_Archive''' is missing.
+
+ Sample_Archive_Default::
+ Focus_Archive_Default::
+ OSA_Archive_Default::
+ OSA Focus_Archive_Default::
+ Detector_Archive_Default::
+ Motor_Archive_Default::
+ Motor2D_Archive_Default::
+   "yes": files are archived \\
+   "no": files are put in the discard sub directory \\
+   "locked": as yes, but users cannot toggle the archive flag for this scan type \\
+   '''Default''': "locked"
+
+Users can toggle the archive flag for a scan type (unless locked).
+When they do so, '''''ScanType''_Archive''' is added or updated.
+
+ Sample_Archive::
+ Focus_Archive::
+ OSA_Archive::
+ OSA Focus_Archive::
+ Detector_Archive::
+ Motor_Archive::
+ Motor2D_Archive::
+   "yes": files are archived \\
+   "no": files are put in the discard sub directory \\
+   '''Default''': '''''ScanType''_Archive_Default'''
+
+### Scan Files
+The name of the file is:
+''ScanType''_''YYYY-mm-dd''_''ScanNumber''.hdf5
+
+For Sample scans, the spatial type
+- _Point
+- _Line
+- _Image
+- _Stack
+is added after ''ScanType''.
+
+ScanNumber is a three digit number, starting with 001 every day.
+
+ NeXusScanNumber::
+   ScanNumber counter \\
+   Updated every time a new scan file is created (beginning of the scan). \\
+   '''Default''': 0
+
+ compression::
+   "LZW": Use LZW compression in hdf5 file \\
+   "NONE": No compression \\
+   '''Default''': "NONE"
+
+ beamline::
+   String value that is written into the scan file at ''/entry*/collection/beamline''
+
+### scripts
+ changeUserScript::
+   name of the script that is run on startup and whenever the user is changed \\
+   '''Optional''': no script is run when this setting is missing
+
+ defaultUsername::
+   username set on startup
+
+ endOfScanScript::
+   name of the script that is run on the controller at the end of every scan \\
+   '''Optional''': no script is run when this setting is missing
+
+### ZeroMQ Ports
+ publisherPort::
+   TCP port used to publish messages
+
+ requestPort::
+   TCP port used to listen for requests
+
+### missing data check
+At the end of a point by point line, some data of asynchronous detectors may be missing.
+They are read until no more data is missing.
+
+ missingDataCheckInterval::
+   interval (in seconds) at which missing data is read \\
+   '''Default''': 0.1 seconds
+
+ missingDataCheckMaxChecks::
+   maximum number of times missing data is read
+   '''Default''': 5
+
+### settings files names
+The following settings define the name of additional settings files.
+Each of these settings files is described in a section below.
+ axisConfigFileName::
+   [#Axis Axis]
+
+ controllerConfigFileName::
+   [#Controller Controller]
+
+ detectorConfigFileName::
+   [#Detector Detector]
+
+ epicsConfigFileName::
+   [#Epics Epics]
+
+ instrumentConfigFileName::
+   [#Instrument Instrument]
+
+ log4cppPropertiesFileName::
+   [#Log4cppProperties Log4cpp Properties]
+
+ microscopeControlConfigFileName::
+   [#MicroscopeControl Microscope Control]
+
+ pixelClockConfigFileName::
+   [#PixelClock Pixel Clock]
+
+ polarizationConfigFileName::
+   [#Polarization Polarization]
+
+ positionerConfigFileName::
+   [#Positioner Positioner]
+
+ topupConfigFileName::
+   '''Optional''': no topup handling when this setting is missing or the file cannot be read. \\
+   [#Topup Topup]
+
+ zonePlateConfigFileName::
+   [#ZonePlate Zone Plate]
+
+## Axis
+
+## Controller
+
+## Detector
+
+## Epics
+This file contains global epics settings.
+
+See source:trunk/PixelatorController/config/epics.json for an example.
+
+ search_timeout::
+   Float value defines the timeout (in seconds) used in
+   * EpicsDetector and EpicsPositioner for
+     * searching channels (casearch)
+   * Epics for
+     * searching channel (casearch) (Topup)
+     * searching channel (casearch) (getStringValue)
+
+   '''Default''': 5.0
+
+ get_timeout::
+   Float value defines the timeout (in seconds) used in
+   * EpicsDetector and EpicsPositioner for
+     * initializing channels (cainfo, caget)
+     * setup monitors (ca_add_event, ca_add_array_event)
+     * set position (ca_put_callback)
+   * Epics for
+     * initializing channel (cainfo) (Topup)
+     * setup monitors (ca_add_event) (Topup)
+     * initializing channel (caget) (getStringValue)
+
+   '''Default''': 1.0
+
+
+## Instrument
+This file defines the content of the NXinstrument group of the scan file (hdf5).
+It is a json object with as many entries as needed. One group is made inside the NXinstrument group
+per entry of this settings file, with the key used as group name.
+
+See source:trunk/PixelatorController/config/instrument.json for an example.
+
+'''NeXus class''' \\
+Every top level entry may have a "class" member that is used as the NeXus class of the group.
+Without the "class" member, the NeXus class of the group is built using the groups name: "NX" + lower(name) \\
+
+Values can be
+* strings
+* numbers
+* [#positionerValues positioner values]
+* arrays of numbers or [#positionerValues positioner values]
+* [#unitValues value with unit]
+* objects \\
+  a nested NeXus group is created \\
+  these nested objects must have a "class" member
+
+[=#conditionalWriting '''Conditional writing'''] \\
+A group may be written conditionally. When a settings object has a "condition" member, its value defines a condition
+that must be met in order to write the entire group. The value of the condition has the form:
+ {{{ {"operator" : [values]} }}}
+values can be
+* strings
+* numbers
+* [#positionerValues positioner values]
+* [#epicsChannelValues epics channel values]
+
+Only one operator is implemented so far:
+* {{{ {"==" : [value1, value2]} }}}
+
+[=#positionerValues '''Positioner values'''] \\
+To write the (numeric) value of a positioner to the NXinstrument section or to use it in a [#conditionalWriting condition],
+a value can be a json object with the following members:
+* positioner: Name of a [#Positioner Positioner]
+* factor (optional): float value. The positioners value is multiplied with this factor.
+* offset (optional): float value. The positioners value is added to this offset.
+
+[=#epicsChannelValues '''Epics channel values'''] \\
+To use the (string) value of an epics channel in a [#conditionalWriting condition],
+a value can be a json object with the following member:
+* epicsChannel: Address of an EPICS channel
+
+[=#unitValues '''Value with unit'''] \\
+As all numeric values should be written with a unit,
+a value can be a json object with value and unit:
+ {{{ {"value" : value, "unit" : unit} }}}
+value can be
+* numbers
+* arrays of numbers
+unit must be a string
+
+## Log4cpp Properties
+
+## Microscope Control
+
+## Pixel Clock
+This file contains the pixel clock settings. It can have multiple pixel clock
+definitions, but only one of them can be active. The key of each pixel clock
+definition is the name of that pixel clock.
+
+See source:trunk/PixelatorController/config/pixelClock.json for an example.
+
+ active::
+   Integer value 1 activates this pixel clock. \\
+   '''Default''': 0
+
+ devicePath::
+   String value defines the comedi device path. \\
+   '''Default''': "" (empty string)
+
+ maxCounters::
+   Integer value defines the maximal number of subdevices. \\
+   '''Default''': 0
+
+ noHardware::
+   Boolean value. Set to true to use PixelatorController without hardware. \\
+   '''Default''': false
+
+ waitUntilDoneInterval::
+   Double value defines the interval (in seconds) used in waitUntilDone().
+   running() is called in this interval until it returns false or
+   until waitUntilDoneTimeout is exceeded. \\
+   '''Default''': 0.005
+
+ waitUntilDoneTimeout::
+   Double value defines the timeout (in seconds) used in waitUntilDone().
+   running() is called until it returns false or until waitUntilDoneTimeout is exceeded. \\
+   '''Default''': 10.0
+
+## Polarization
+
+## Positioner
+This file contains the positioner settings.
+
+See source:trunk/PixelatorController/config/positioner.json for an example.
+
+ atPositionCheckInverval_Default::
+   Double value used for all positioners that don't define their own atPositionCheckInverval. \\
+   '''Default''': 0.002
+
+ atPositionCheckTimeout_Default::
+   Double value used for all positioners that don't define their own atPositionCheckTimeout. \\
+   '''Default''': 10.0
+
+The remaining entries are positioner names with their settings. The settings depend on the positioner type.
+
+### base settings
+The following settings are available for all types of positioners:
+ nexus_name::
+   String value defines the positioners name in the hdf5 file. \\
+   '''Default''': positioner name
+
+ axisName::
+   String value defines the name of the axis moved by this positioner. \\
+   Example: Coarse and Fine X both belong to SampleX. \\
+   '''Default''': positioner name
+
+ description::
+   String value describes the positioner.
+   That value is written to the hdf5 file (NXcollection) and
+   it is sent to PixelatorGUI. \\
+   '''Default''': "" (empty string)
+
+ unit::
+   String value defines the unit of the positioner values (on the GUI and in the hdf5 file). \\
+   '''Default''': "" (empty string)
+
+ hardwareUnitFactor::
+   Double value defines the conversion factor used to convert hardware positioner values to '''unit'''. \\
+   '''Default''': 1.0
+
+ distributionMode::
+   String value defines the discribution of points to an interval. \\
+   Example: 5 points from 0 to 10:
+   * "n": 0, 2.5, 5, 7.5, 10
+   * "nPlus1": 0, 2, 4, 6, 8, 10
+
+   '''Default''': "n"
+
+ positionOffset::
+   Double value defines . \\
+   '''Default''': 0.0
+
+ upperSoftLimit::
+   Double value defines . \\
+   '''Default''': 0.0
+
+ lowerSoftLimit::
+   Double value defines . \\
+   '''Default''': 0.0
+
+ coarsePositioner::
+   String value defines . \\
+   '''Default''': "" (empty string)
+
+ finePositioner::
+   String value defines . \\
+   '''Default''': "" (empty string)
+
+ maxVelocity::
+   Double value defines . \\
+   '''Default''': 0.0
+
+ readOnly::
+   Boolean value true when the positioner can only be used to read its position. \\
+   '''Default''': false
+
+ autoOff::
+   String value defines . \\
+   * "Never" : 
+
+   '''Default''': "Never"
+
+ beamlineControlPosition::
+   Unsigned integer value defines . \\
+   '''Default''': 0
+
+ epsilon::
+   Double value defines . \\
+   '''Default''': 0.1
+
+ atPositionCheckInverval::
+   Double value defines the interval (in seconds) used in waitDoneMoving().
+   getStatus() is called in this interval as long as it returns moving or
+   until atPositionCheckTimeout is exceeded. \\
+   '''Default''': atPositionCheckInverval_Default (see above)
+
+ atPositionCheckTimeout::
+   Double value defines the timeout (in seconds) used in waitDoneMoving().
+   getStatus() is called as long as it returns moving or until atPositionCheckTimeout is exceeded. \\
+   '''Default''': atPositionCheckTimeout_Default (see above)
+
+ stringPositions::
+   Optional array of objects with members
+   * '''string''': String value defines the position name
+   * '''position''': Double value defines the position value
+
+   These objects can be used to get
+   * a name of a position value (positionUserToStringHardware)
+   * the position of a named position (stringHardwareToPositionUser)
+
+== Topup ==
+This file contains the topup settings.
+
+See source:trunk/PixelatorController/config/topup.json for an example.
+
+ active::
+   Integer value 1 activates topup handling. \\
+   '''Default''': 0
+
+ channel::
+   String value defines the EPICS address of the topup channel. \\
+   Mandatory for topup handling.
+
+ wait_time::
+   Float value defines the delay (in seconds) between when the topup signal stops and when stxm measurements resume. \\
+   See ticket #382. \\
+   '''Default''': 0
+ 
+## Zone Plate
\ No newline at end of file