Menu
▾
▴
[Emc-commit] v2.5_branch: Docs: markup fixes
|
From: John T. <gi...@gi...> - 2011-12-14 18:51:55
|
Docs: markup fixes Signed-off-by: John Thornton <jth...@gn...> http://git.linuxcnc.org/?p=emc2.git;a=commitdiff;h=2d0ee8f --- docs/src/gui/image-to-gcode.txt | 53 ++++++----- docs/src/gui/image-to-gcode_de.txt | 57 ++++++----- docs/src/gui/image-to-gcode_es.txt | 57 ++++++----- docs/src/gui/image-to-gcode_pl.txt | 57 ++++++----- docs/src/hal/intro.txt | 176 ++++++----------------------------- docs/src/hal/intro_de.txt | 183 ++++++------------------------------ docs/src/hal/intro_es.txt | 183 ++++++------------------------------ docs/src/hal/intro_pl.txt | 181 ++++++------------------------------ 8 files changed, 244 insertions(+), 703 deletions(-) diff --git a/docs/src/gui/image-to-gcode.txt b/docs/src/gui/image-to-gcode.txt index 7ecb3b4..ac4b439 100644 --- a/docs/src/gui/image-to-gcode.txt +++ b/docs/src/gui/image-to-gcode.txt @@ -1,4 +1,7 @@ -= Image-to-gcode: Milling âdepth mapsâ +:lang: en +:toc: + += Image-to-gcode image::images/image-to-gcode.png[] @@ -9,16 +12,18 @@ corresponds to the depth (or height) of the object at each point. == Integrating image-to-gcode with the AXIS user interface -Add the following lines to the `[FILTER]` section of your .ini file +Add the following lines to the '[FILTER]' section of your .ini file to make AXIS automatically invoke image-to-gcode when you open a .png, .gif, or .jpg image - PROGRAM_EXTENSION = .png,.gif,.jpg Grayscale Depth Image - png = image-to-gcode - gif = image-to-gcode - jpg = image-to-gcode +---- +PROGRAM_EXTENSION = .png,.gif,.jpg Grayscale Depth Image +png = image-to-gcode +gif = image-to-gcode +jpg = image-to-gcode +---- -The standard `sim/axis.ini` configuration file is already configured +The standard 'sim/axis.ini' configuration file is already configured this way. == Using image-to-gcode @@ -26,7 +31,9 @@ this way. Start image-to-gcode either by opening an image file in AXIS, or by invoking image-to-gcode from the terminal, as follows: - image-to-gcode torus.png > torus.ngc +---- +image-to-gcode torus.png > torus.ngc +---- Verify all the settings in the right-hand column, then press OK to create the gcode. Depending on the image size and options chosen, this @@ -40,7 +47,7 @@ image-to-gcode option screen again, allowing you to tweak them. === Units Specifies whether to use G20 (inches) or G21 (mm) in the generated -g-code and as the units for each option labeled *(units)*. +g-code and as the units for each option labeled '(units)'. === Invert Image @@ -50,19 +57,19 @@ the white pixel is the lowest point. === Normalize Image -If âyesâ, the darkest pixel is remapped to black, the lightest pixel +If 'yes', the darkest pixel is remapped to black, the lightest pixel is remapped to white. === Expand Image Border -If âNoneâ, the input image is used as-is, and details which are at the -very edges of the image may be cut off. If âWhiteâ or âBlackâ, then a +If 'None', the input image is used as-is, and details which are at the +very edges of the image may be cut off. If 'White' or 'Black', then a border of pixels equal to the tool diameter is added on all sides, and details which are at the very edges of the images will not be cut off. === Tolerance (units) -When a series of points are within *tolerance* of being a straight +When a series of points are within 'tolerance' of being a straight line, they are output as a straight line. Increasing tolerance can lead to better contouring performance in EMC2, but can also remove or blur small details in the image. @@ -110,16 +117,16 @@ Possible scan directions are: === Depth (units) -The top of material is always at *Z=0*. The deepest cut into the -material is *Z=-depth.* +The top of material is always at 'Z=0'. The deepest cut into the +material is 'Z=-depth.' === Step Over (pixels) The distance between adjacent rows or columns. To find the number of -pixels for a given units distance, compute *distance/pixel size* and -round to the nearest whole number'.' For example, if *pixel size=.006* -and the desired step over *distance=.015*, then use a Step Over of 2 or -3 pixels, because *.015/.006=2.5*'.' +pixels for a given units distance, compute 'distance/pixel size' and +round to the nearest whole number. For example, if 'pixel size=.006' +and the desired step over 'distance=.015', then use a Step Over of 2 or +3 pixels, because '.015/.006=2.5''.' === Tool Diameter @@ -128,7 +135,7 @@ The diameter of the cutting part of the tool. === Safety Height The height to move to for traverse movements. image-to-gcode always -assumes the top of material is at *Z=0*. +assumes the top of material is at 'Z=0'. === Tool Type @@ -155,14 +162,14 @@ columns are being milled. Possible bounding options are: === Contact angle -When *Lace bounding* is not `None`, slopes greater than *Contact angle* -are considered to be âstrongâ slopes, and slopes less than that angle +When 'Lace bounding' is not 'None', slopes greater than 'Contact angle' +are considered to be 'strong' slopes, and slopes less than that angle are considered to be weak slopes. === Roughing offset and depth per pass Image-to-gcode can optionally perform rouging passes. The depth of -successive roughing passes is given by âRoughing depth per passâ. For +successive roughing passes is given by 'Roughing depth per pass'. For instance, entering 0.2 will perform the first roughing pass with a depth of 0.2, the second roughing pass with a depth of 0.4, and so on until the full Depth of the image is reached. No part of any roughing diff --git a/docs/src/gui/image-to-gcode_de.txt b/docs/src/gui/image-to-gcode_de.txt index cb0c755..7798d27 100644 --- a/docs/src/gui/image-to-gcode_de.txt +++ b/docs/src/gui/image-to-gcode_de.txt @@ -1,6 +1,9 @@ -= Image-to-gcode: Milling âdepth mapsâ +:lang: de +:toc: -image:images/image-to-gcode.png[] += Image-to-gcode + +image::images/image-to-gcode.png[] == What is a depth map? @@ -9,16 +12,18 @@ corresponds to the depth (or height) of the object at each point. == Integrating image-to-gcode with the AXIS user interface -Add the following lines to the `[FILTER]` section of your .ini file +Add the following lines to the '[FILTER]' section of your .ini file to make AXIS automatically invoke -image-to-gcode when you open a .png, .gif, or .jpg image: +image-to-gcode when you open a .png, .gif, or .jpg image - PROGRAM_EXTENSION = .png,.gif,.jpg Grayscale Depth Image - png = image-to-gcode - gif = image-to-gcode - jpg = image-to-gcode +---- +PROGRAM_EXTENSION = .png,.gif,.jpg Grayscale Depth Image +png = image-to-gcode +gif = image-to-gcode +jpg = image-to-gcode +---- -The standard `sim/axis.ini` configuration file is already configured +The standard 'sim/axis.ini' configuration file is already configured this way. == Using image-to-gcode @@ -26,7 +31,9 @@ this way. Start image-to-gcode either by opening an image file in AXIS, or by invoking image-to-gcode from the terminal, as follows: - image-to-gcode torus.png > torus.ngc +---- +image-to-gcode torus.png > torus.ngc +---- Verify all the settings in the right-hand column, then press OK to create the gcode. Depending on the image size and options chosen, this @@ -40,7 +47,7 @@ image-to-gcode option screen again, allowing you to tweak them. === Units Specifies whether to use G20 (inches) or G21 (mm) in the generated -g-code and as the units for each option labeled *(units)*. +g-code and as the units for each option labeled '(units)'. === Invert Image @@ -50,19 +57,19 @@ the white pixel is the lowest point. === Normalize Image -If âyesâ, the darkest pixel is remapped to black, the lightest pixel +If 'yes', the darkest pixel is remapped to black, the lightest pixel is remapped to white. === Expand Image Border -If âNoneâ, the input image is used as-is, and details which are at the -very edges of the image may be cut off. If âWhiteâ or âBlackâ, then a +If 'None', the input image is used as-is, and details which are at the +very edges of the image may be cut off. If 'White' or 'Black', then a border of pixels equal to the tool diameter is added on all sides, and details which are at the very edges of the images will not be cut off. === Tolerance (units) -When a series of points are within *tolerance* of being a straight +When a series of points are within 'tolerance' of being a straight line, they are output as a straight line. Increasing tolerance can lead to better contouring performance in EMC2, but can also remove or blur small details in the image. @@ -110,16 +117,16 @@ Possible scan directions are: === Depth (units) -The top of material is always at *Z=0*. The deepest cut into the -material is *Z=-depth.* +The top of material is always at 'Z=0'. The deepest cut into the +material is 'Z=-depth.' === Step Over (pixels) The distance between adjacent rows or columns. To find the number of -pixels for a given units distance, compute *distance/pixel size* and -round to the nearest whole number'.' For example, if *pixel size=.006* -and the desired step over *distance=.015*, then use a Step Over of 2 or -3 pixels, because *.015/.006=2.5*'.' +pixels for a given units distance, compute 'distance/pixel size' and +round to the nearest whole number. For example, if 'pixel size=.006' +and the desired step over 'distance=.015', then use a Step Over of 2 or +3 pixels, because '.015/.006=2.5''.' === Tool Diameter @@ -128,7 +135,7 @@ The diameter of the cutting part of the tool. === Safety Height The height to move to for traverse movements. image-to-gcode always -assumes the top of material is at *Z=0*. +assumes the top of material is at 'Z=0'. === Tool Type @@ -155,14 +162,14 @@ columns are being milled. Possible bounding options are: === Contact angle -When *Lace bounding* is not `None`, slopes greater than *Contact angle* -are considered to be âstrongâ slopes, and slopes less than that angle +When 'Lace bounding' is not 'None', slopes greater than 'Contact angle' +are considered to be 'strong' slopes, and slopes less than that angle are considered to be weak slopes. === Roughing offset and depth per pass Image-to-gcode can optionally perform rouging passes. The depth of -successive roughing passes is given by âRoughing depth per passâ. For +successive roughing passes is given by 'Roughing depth per pass'. For instance, entering 0.2 will perform the first roughing pass with a depth of 0.2, the second roughing pass with a depth of 0.4, and so on until the full Depth of the image is reached. No part of any roughing diff --git a/docs/src/gui/image-to-gcode_es.txt b/docs/src/gui/image-to-gcode_es.txt index cb0c755..038d7da 100644 --- a/docs/src/gui/image-to-gcode_es.txt +++ b/docs/src/gui/image-to-gcode_es.txt @@ -1,6 +1,9 @@ -= Image-to-gcode: Milling âdepth mapsâ +:lang: es +:toc: -image:images/image-to-gcode.png[] += Image-to-gcode + +image::images/image-to-gcode.png[] == What is a depth map? @@ -9,16 +12,18 @@ corresponds to the depth (or height) of the object at each point. == Integrating image-to-gcode with the AXIS user interface -Add the following lines to the `[FILTER]` section of your .ini file +Add the following lines to the '[FILTER]' section of your .ini file to make AXIS automatically invoke -image-to-gcode when you open a .png, .gif, or .jpg image: +image-to-gcode when you open a .png, .gif, or .jpg image - PROGRAM_EXTENSION = .png,.gif,.jpg Grayscale Depth Image - png = image-to-gcode - gif = image-to-gcode - jpg = image-to-gcode +---- +PROGRAM_EXTENSION = .png,.gif,.jpg Grayscale Depth Image +png = image-to-gcode +gif = image-to-gcode +jpg = image-to-gcode +---- -The standard `sim/axis.ini` configuration file is already configured +The standard 'sim/axis.ini' configuration file is already configured this way. == Using image-to-gcode @@ -26,7 +31,9 @@ this way. Start image-to-gcode either by opening an image file in AXIS, or by invoking image-to-gcode from the terminal, as follows: - image-to-gcode torus.png > torus.ngc +---- +image-to-gcode torus.png > torus.ngc +---- Verify all the settings in the right-hand column, then press OK to create the gcode. Depending on the image size and options chosen, this @@ -40,7 +47,7 @@ image-to-gcode option screen again, allowing you to tweak them. === Units Specifies whether to use G20 (inches) or G21 (mm) in the generated -g-code and as the units for each option labeled *(units)*. +g-code and as the units for each option labeled '(units)'. === Invert Image @@ -50,19 +57,19 @@ the white pixel is the lowest point. === Normalize Image -If âyesâ, the darkest pixel is remapped to black, the lightest pixel +If 'yes', the darkest pixel is remapped to black, the lightest pixel is remapped to white. === Expand Image Border -If âNoneâ, the input image is used as-is, and details which are at the -very edges of the image may be cut off. If âWhiteâ or âBlackâ, then a +If 'None', the input image is used as-is, and details which are at the +very edges of the image may be cut off. If 'White' or 'Black', then a border of pixels equal to the tool diameter is added on all sides, and details which are at the very edges of the images will not be cut off. === Tolerance (units) -When a series of points are within *tolerance* of being a straight +When a series of points are within 'tolerance' of being a straight line, they are output as a straight line. Increasing tolerance can lead to better contouring performance in EMC2, but can also remove or blur small details in the image. @@ -110,16 +117,16 @@ Possible scan directions are: === Depth (units) -The top of material is always at *Z=0*. The deepest cut into the -material is *Z=-depth.* +The top of material is always at 'Z=0'. The deepest cut into the +material is 'Z=-depth.' === Step Over (pixels) The distance between adjacent rows or columns. To find the number of -pixels for a given units distance, compute *distance/pixel size* and -round to the nearest whole number'.' For example, if *pixel size=.006* -and the desired step over *distance=.015*, then use a Step Over of 2 or -3 pixels, because *.015/.006=2.5*'.' +pixels for a given units distance, compute 'distance/pixel size' and +round to the nearest whole number. For example, if 'pixel size=.006' +and the desired step over 'distance=.015', then use a Step Over of 2 or +3 pixels, because '.015/.006=2.5''.' === Tool Diameter @@ -128,7 +135,7 @@ The diameter of the cutting part of the tool. === Safety Height The height to move to for traverse movements. image-to-gcode always -assumes the top of material is at *Z=0*. +assumes the top of material is at 'Z=0'. === Tool Type @@ -155,14 +162,14 @@ columns are being milled. Possible bounding options are: === Contact angle -When *Lace bounding* is not `None`, slopes greater than *Contact angle* -are considered to be âstrongâ slopes, and slopes less than that angle +When 'Lace bounding' is not 'None', slopes greater than 'Contact angle' +are considered to be 'strong' slopes, and slopes less than that angle are considered to be weak slopes. === Roughing offset and depth per pass Image-to-gcode can optionally perform rouging passes. The depth of -successive roughing passes is given by âRoughing depth per passâ. For +successive roughing passes is given by 'Roughing depth per pass'. For instance, entering 0.2 will perform the first roughing pass with a depth of 0.2, the second roughing pass with a depth of 0.4, and so on until the full Depth of the image is reached. No part of any roughing diff --git a/docs/src/gui/image-to-gcode_pl.txt b/docs/src/gui/image-to-gcode_pl.txt index cb0c755..deb918d 100644 --- a/docs/src/gui/image-to-gcode_pl.txt +++ b/docs/src/gui/image-to-gcode_pl.txt @@ -1,6 +1,9 @@ -= Image-to-gcode: Milling âdepth mapsâ +:lang: pl +:toc: -image:images/image-to-gcode.png[] += Image-to-gcode + +image::images/image-to-gcode.png[] == What is a depth map? @@ -9,16 +12,18 @@ corresponds to the depth (or height) of the object at each point. == Integrating image-to-gcode with the AXIS user interface -Add the following lines to the `[FILTER]` section of your .ini file +Add the following lines to the '[FILTER]' section of your .ini file to make AXIS automatically invoke -image-to-gcode when you open a .png, .gif, or .jpg image: +image-to-gcode when you open a .png, .gif, or .jpg image - PROGRAM_EXTENSION = .png,.gif,.jpg Grayscale Depth Image - png = image-to-gcode - gif = image-to-gcode - jpg = image-to-gcode +---- +PROGRAM_EXTENSION = .png,.gif,.jpg Grayscale Depth Image +png = image-to-gcode +gif = image-to-gcode +jpg = image-to-gcode +---- -The standard `sim/axis.ini` configuration file is already configured +The standard 'sim/axis.ini' configuration file is already configured this way. == Using image-to-gcode @@ -26,7 +31,9 @@ this way. Start image-to-gcode either by opening an image file in AXIS, or by invoking image-to-gcode from the terminal, as follows: - image-to-gcode torus.png > torus.ngc +---- +image-to-gcode torus.png > torus.ngc +---- Verify all the settings in the right-hand column, then press OK to create the gcode. Depending on the image size and options chosen, this @@ -40,7 +47,7 @@ image-to-gcode option screen again, allowing you to tweak them. === Units Specifies whether to use G20 (inches) or G21 (mm) in the generated -g-code and as the units for each option labeled *(units)*. +g-code and as the units for each option labeled '(units)'. === Invert Image @@ -50,19 +57,19 @@ the white pixel is the lowest point. === Normalize Image -If âyesâ, the darkest pixel is remapped to black, the lightest pixel +If 'yes', the darkest pixel is remapped to black, the lightest pixel is remapped to white. === Expand Image Border -If âNoneâ, the input image is used as-is, and details which are at the -very edges of the image may be cut off. If âWhiteâ or âBlackâ, then a +If 'None', the input image is used as-is, and details which are at the +very edges of the image may be cut off. If 'White' or 'Black', then a border of pixels equal to the tool diameter is added on all sides, and details which are at the very edges of the images will not be cut off. === Tolerance (units) -When a series of points are within *tolerance* of being a straight +When a series of points are within 'tolerance' of being a straight line, they are output as a straight line. Increasing tolerance can lead to better contouring performance in EMC2, but can also remove or blur small details in the image. @@ -110,16 +117,16 @@ Possible scan directions are: === Depth (units) -The top of material is always at *Z=0*. The deepest cut into the -material is *Z=-depth.* +The top of material is always at 'Z=0'. The deepest cut into the +material is 'Z=-depth.' === Step Over (pixels) The distance between adjacent rows or columns. To find the number of -pixels for a given units distance, compute *distance/pixel size* and -round to the nearest whole number'.' For example, if *pixel size=.006* -and the desired step over *distance=.015*, then use a Step Over of 2 or -3 pixels, because *.015/.006=2.5*'.' +pixels for a given units distance, compute 'distance/pixel size' and +round to the nearest whole number. For example, if 'pixel size=.006' +and the desired step over 'distance=.015', then use a Step Over of 2 or +3 pixels, because '.015/.006=2.5''.' === Tool Diameter @@ -128,7 +135,7 @@ The diameter of the cutting part of the tool. === Safety Height The height to move to for traverse movements. image-to-gcode always -assumes the top of material is at *Z=0*. +assumes the top of material is at 'Z=0'. === Tool Type @@ -155,14 +162,14 @@ columns are being milled. Possible bounding options are: === Contact angle -When *Lace bounding* is not `None`, slopes greater than *Contact angle* -are considered to be âstrongâ slopes, and slopes less than that angle +When 'Lace bounding' is not 'None', slopes greater than 'Contact angle' +are considered to be 'strong' slopes, and slopes less than that angle are considered to be weak slopes. === Roughing offset and depth per pass Image-to-gcode can optionally perform rouging passes. The depth of -successive roughing passes is given by âRoughing depth per passâ. For +successive roughing passes is given by 'Roughing depth per pass'. For instance, entering 0.2 will perform the first roughing pass with a depth of 0.2, the second roughing pass with a depth of 0.4, and so on until the full Depth of the image is reached. No part of any roughing diff --git a/docs/src/hal/intro.txt b/docs/src/hal/intro.txt index d759689..6a6eedc 100644 --- a/docs/src/hal/intro.txt +++ b/docs/src/hal/intro.txt @@ -1,8 +1,11 @@ +:lang: en +:toc: + = Introduction[[cha:Introduction]] HAL(((HAL))) stands for Hardware Abstraction Layer. At the highest -level, it is simply a way to allow a number of âbuilding blocksâ to be -loaded and interconnected to assemble a complex system. The âHardwareâ +level, it is simply a way to allow a number of 'building blocks' to be +loaded and interconnected to assemble a complex system. The 'Hardware' part is because HAL was originally designed to make it easier to configure EMC for a wide variety of hardware devices. Many of the building blocks are drivers for hardware devices. However, HAL can do @@ -61,10 +64,10 @@ interconnected according to the wiring diagram. In a physical system, each interconnection is a piece of wire that needs to be cut and connected to the appropriate terminals. -HAL provides a number of tools to help âbuildâ a HAL system. Some of -the tools allow you to âconnectâ (or disconnect) a single âwireâ. Other +HAL provides a number of tools to help 'build' a HAL system. Some of +the tools allow you to 'connect' (or disconnect) a single 'wire'. Other tools allow you to save a complete list of all the parts, wires, and -other information about the system, so that it can be ârebuiltâ with a +other information about the system, so that it can be 'rebuilt' with a single command. === Testing @@ -99,7 +102,7 @@ HAL extends this traditional hardware design method to the inside of the big black box. It makes device drivers and even some internal parts of the controller into smaller black boxes that can be interconnected and even replaced just like the external hardware. It allows the -âsystem wiring diagramâ to show part of the internal controller, rather +'system wiring diagram' to show part of the internal controller, rather than just a big black box. And most importantly, it allows the integrator to test and modify the controller using the same methods he would use on the rest of the hardware. @@ -108,8 +111,8 @@ Terms like motors, amps, and encoders are familiar to most machine integrators. When we talk about using extra flexible eight conductor shielded cable to connect an encoder to the servo input board in the computer, the reader immediately understands what it is and is led to -the question, âwhat kinds of connectors will I need to make up each -end.â The same sort of thinking is essential for the HAL but the +the question, 'what kinds of connectors will I need to make up each +end.' The same sort of thinking is essential for the HAL but the specific train of thought may take a bit to get on track. Using HAL words may seem a bit strange at first, but the concept of working from one connection to the next is the same. @@ -128,10 +131,10 @@ or flow in the HAL way of things. Component:: (((HAL Component)))When we talked about hardware design, we referred - to the individual pieces as "parts", "building blocks", "black boxes", - etc. The HAL equivalent is a "component" or "HAL component". (This - document uses "HAL component" when there is likely to be confusion with - other kinds of components, but normally just uses "component".) A HAL + to the individual pieces as 'parts', 'building blocks', 'black boxes', + etc. The HAL equivalent is a 'component' or 'HAL component'. (This + document uses 'HAL component' when there is likely to be confusion with + other kinds of components, but normally just uses 'component'.) A HAL component is a piece of software with well-defined inputs, outputs, and behavior, that can be installed and interconnected as needed. @@ -141,7 +144,7 @@ Parameter:: accessed. For example, servo amps often have trim pots to allow for tuning adjustments, and test points where a meter or scope can be attached to view the tuning results. HAL components also can have such - items, which are referred to as "parameters". There are two types of + items, which are referred to as 'parameters'. There are two types of parameters: Input parameters are equivalent to trim pots - they are values that can be adjusted by the user, and remain fixed once they are set. Output parameters cannot be adjusted by the user - they are @@ -149,8 +152,8 @@ Parameter:: Pin:: (((HAL Pin)))Hardware components have terminals which are used to - interconnect them. The HAL equivalent is a "pin" or "HAL pin". ("HAL - pin" is used when needed to avoid confusion.) All HAL pins are named, + interconnect them. The HAL equivalent is a 'pin' or 'HAL pin'. ('HAL + pin' is used when needed to avoid confusion.) All HAL pins are named, and the pin names are used when interconnecting them. HAL pins are software entities that exist only inside the computer. @@ -158,13 +161,13 @@ Physical_Pin:: (((HAL Physical-Pin)))Many I/O devices have real physical pins or terminals that connect to external hardware, for example the pins of a parallel port connector. To avoid confusion, these are referred to as - "physical pins". These are the things that âstick outâ into the real + 'physical pins'. These are the things that 'stick out' into the real world. Signal:: (((HAL Signal)))In a physical machine, the terminals of real hardware components are interconnected by wires. The HAL equivalent of - a wire is a "signal" or "HAL signal". HAL signals connect HAL pins + a wire is a 'signal' or 'HAL signal'. HAL signals connect HAL pins together as required by the machine builder. HAL signals can be disconnected and reconnected at will (even while the machine is running). @@ -183,11 +186,11 @@ Type:: - s32 - a 32 bit signed integer, legal values are -2,147,483,647 to +2,147,483,647 -Function::[[des:Function]](((HAL Function))) +Function:: Real hardware components tend to act immediately on their inputs. For example, if the input voltage to a servo amp changes, the output also changes automatically. However - software components cannot act "automatically". Each component has + software components cannot act 'automatically'. Each component has specific code that must be executed to do whatever that component is supposed to do. In some cases, that code simply runs as part of the component. However in most cases, especially in realtime components, @@ -195,13 +198,13 @@ Function::[[des:Function]](((HAL Function))) example, inputs should be read before calculations are performed on the input data, and outputs should not be written until the calculations are done. In these cases, the code is made available to the system in - the form of one or more "functions". Each function is a block of code + the form of one or more 'functions'. Each function is a block of code that performs a specific action. The system integrator can use - "threads" to schedule a series of functions to be executed in a + 'threads' to schedule a series of functions to be executed in a particular order and at specific time intervals. -Thread::[[des:Thread]](((HAL Thread))) - A "thread" is a list of functions that +Thread:: + A 'thread' is a list of functions that runs at specific intervals as part of a realtime task. When a thread is first created, it has a specific time interval (period), but no functions. Functions can be added to the thread, and will be executed @@ -309,131 +312,6 @@ halscope:: Each of these building blocks is described in detail in later chapters. -== Tinkertoys, Erector Sets, Legos and the HAL[[sec:Tinkertoys]] - -A first introduction to HAL concepts can be mind boggling. Building -anything with blocks can be a challenge but some of the toys that we -played with as kids can be an aid to building things with the HAL. - -=== Tower - -.Tower -********************************************************************* -I'm watching as my son and his six year old daughter build a tower -from a box full of random sized blocks, rods, jar lids and such. The -aim is to see how tall they can make the tower. The narrower the base -the more blocks left to stack on top. But the narrower the base, the -less stable the tower. I see them studying both the next block and the -shelf where they want to place it to see how it will balance out with -the rest of the tower. -********************************************************************* - -The notion of stacking cards to see how tall you can make a tower is a -very old and honored way of spending spare time. At first read, the -integrator may have gotten the impression that building a HAL was a bit -like that. It can be, but with proper planning an integrator can build a -stable system as complex as the machine at hand requires. - -=== Erector Sets footnote:[The Erector Set was an invention of A.C Gilbert] - -What was great about the sets was the building blocks, metal struts -and angles and plates, all with regularly spaced holes. You could -design things and hold them together with the little screws and nuts. - -.Erector Sets -********************************************************************* -I got my first erector set for my fourth birthday. I know the box -suggested a much older age than I was. Perhaps my father was really -giving himself a present. I had a hard time with the little screws and -nuts. I really needed four arms, one each for the screwdriver, screw, -parts to be bolted together, and nut. Perseverance, along with father's -eventual boredom, got me to where I had built every project in the -booklet. Soon I was lusting after the bigger sets that were also -printed on that paper. Working with those regular sized pieces opened -up a world of construction for me and soon I moved well beyond the -illustrated projects. -********************************************************************* - -HAL components are not all the same size and shape but they allow for -grouping into larger units that will do useful work.In this sense they -are like the parts of an Erector set. Some components are long and -thin. They essentially connect high level commands to specific physical -pins. Other components are more like the rectangular platforms upon -which whole machines could be built. An integrator will quickly get -beyond the brief examples and begin to bolt together components in ways -that are unique to them. - -=== Tinkertoys footnote:[Tinkertoy is now a registered trademark of the Hasbro company. ] - -.Tinkertoys -********************************************************************* -Wooden Tinkertoys had a more humane feel than the cold steel of -Erector Sets. The heart of construction with Tinkertoys was a round -connector with eight holes equally spaced around the circumference. It -also had a hole in the center that was perpendicular to all the holes -around the hub. - -Hubs were connected with rods of several different lengths. Builders -would make large wheels by using these rods as spokes sticking out from -the center hub. - -My favorite project was a rotating space station. Short spokes -radiated from all the holes in the center hub and connected with hubs -on the ends of each spoke. These outer hubs were connected to each -other with longer spokes. I'd spend hours dreaming of living in such a -device, walking from hub to hub around the outside as it slowly rotated -producing near gravity in weightless space. Supplies traveled through -the spokes in elevators that transferred them to and from rockets docked -at the center hub while they transferred their precious cargoes. -********************************************************************* - -The idea of one pin or component being the hub for many connections is -also an easy concept within the HAL. Examples two and four (see section - <<cha:HAL-Tutorial>>) connect the meter and scope to signals that are -intended to go elsewhere. Less easy is the notion of a hub for several -incoming signals but that is also possible with proper use of functions -within that hub component that handle those signals as they arrive from -other components. - -Another thought that comes forward from this toy is a mechanical -representation of HAL threads. A thread might look a bit like a -centipede, caterpillar, or earwig. A backbone of hubs, HAL components, -strung together with rods, HAL signals. Each component takes in it own -parameters and input pins and passes on output pins and parameters to -the next component. Signals travel along the backbone from end to end -and are added to or modified by each component in turn. - -Threads are all about timing and doing a set of tasks from end to end. -A mechanical representation is available with Tinkertoys also when we -think of the length of the toy as a measure of the time taken to get -from one end to the other. A very different thread or backbone is -created by connecting the same set of hubs with different length rods. -The total length of the backbone can be changed by the length of rods -used to connect the hubs. The order of operations is the same but the -time to get from beginning to end is very different. - -=== A Lego Example footnote:[The Lego name is a trademark of the Lego company.][[sub:A-Lego-Example]] - -When Lego blocks first arrived in our stores they were pretty much all -the same size and shape. Sure there were half sized one and a few -quarter sized as well but that rectangular one did most of the work. -Lego blocks interconnected by snapping the holes in the underside of -one onto the pins that stuck up on another. By overlapping layers, the -joints between could be made very strong, even around corners or tees. - -.Legos -********************************************************************* -I watched my children and grandchildren build with Legos -- the same -Legos. There are a few thousand of them in an old ratty but heavy duty -cardboard box that sits in a corner of the recreation room. It stays -there in the open because it was too much trouble to put the box away -and then get it back out for every visit and it is always used during a -visit. There must be Lego parts in there from a couple dozen different -sets. The little booklets that came with them are long gone but the -magic of building with interlocking pieces all the same size is -something to watch. -********************************************************************* - == Timing Issues In HAL[[sec:Timing-Issues]] Unlike the physical wiring models between black boxes that we have @@ -442,7 +320,7 @@ hal-signal falls far short of the action of the physical case. True relay logic consists of relays connected together, and when a contact opens or closes, current flows (or stops) immediately. Other -coils may change state, etc, and it all just "happens". But in PLC +coils may change state, etc, and it all just 'happens'. But in PLC style ladder logic, it doesn't work that way. Usually in a single pass through the ladder, each rung is evaluated in the order in which it appears, and only once per pass. A perfect example is a single rung diff --git a/docs/src/hal/intro_de.txt b/docs/src/hal/intro_de.txt index 91507eb..420058f 100644 --- a/docs/src/hal/intro_de.txt +++ b/docs/src/hal/intro_de.txt @@ -1,8 +1,11 @@ +:lang: de +:toc: + = Introduction[[cha:Introduction]] HAL(((HAL))) stands for Hardware Abstraction Layer. At the highest -level, it is simply a way to allow a number of âbuilding blocksâ to be -loaded and interconnected to assemble a complex system. The âHardwareâ +level, it is simply a way to allow a number of 'building blocks' to be +loaded and interconnected to assemble a complex system. The 'Hardware' part is because HAL was originally designed to make it easier to configure EMC for a wide variety of hardware devices. Many of the building blocks are drivers for hardware devices. However, HAL can do @@ -61,10 +64,10 @@ interconnected according to the wiring diagram. In a physical system, each interconnection is a piece of wire that needs to be cut and connected to the appropriate terminals. -HAL provides a number of tools to help âbuildâ a HAL system. Some of -the tools allow you to âconnectâ (or disconnect) a single âwireâ. Other +HAL provides a number of tools to help 'build' a HAL system. Some of +the tools allow you to 'connect' (or disconnect) a single 'wire'. Other tools allow you to save a complete list of all the parts, wires, and -other information about the system, so that it can be ârebuiltâ with a +other information about the system, so that it can be 'rebuilt' with a single command. === Testing @@ -86,7 +89,9 @@ changes as needed. This document is aimed at people who already know how to do this kind of hardware system integration, but who do not know how to connect the -hardware to EMC. +hardware to EMC. See Remote Start Example<<fig:Remote-Start-Example>> + +image::images/remote-start.png[] The traditional hardware design as described above ends at the edge of the main control. Outside the control are a bunch of relatively simple @@ -97,7 +102,7 @@ HAL extends this traditional hardware design method to the inside of the big black box. It makes device drivers and even some internal parts of the controller into smaller black boxes that can be interconnected and even replaced just like the external hardware. It allows the -âsystem wiring diagramâ to show part of the internal controller, rather +'system wiring diagram' to show part of the internal controller, rather than just a big black box. And most importantly, it allows the integrator to test and modify the controller using the same methods he would use on the rest of the hardware. @@ -106,8 +111,8 @@ Terms like motors, amps, and encoders are familiar to most machine integrators. When we talk about using extra flexible eight conductor shielded cable to connect an encoder to the servo input board in the computer, the reader immediately understands what it is and is led to -the question, âwhat kinds of connectors will I need to make up each -end.â The same sort of thinking is essential for the HAL but the +the question, 'what kinds of connectors will I need to make up each +end.' The same sort of thinking is essential for the HAL but the specific train of thought may take a bit to get on track. Using HAL words may seem a bit strange at first, but the concept of working from one connection to the next is the same. @@ -126,10 +131,10 @@ or flow in the HAL way of things. Component:: (((HAL Component)))When we talked about hardware design, we referred - to the individual pieces as "parts", "building blocks", "black boxes", - etc. The HAL equivalent is a "component" or "HAL component". (This - document uses "HAL component" when there is likely to be confusion with - other kinds of components, but normally just uses "component".) A HAL + to the individual pieces as 'parts', 'building blocks', 'black boxes', + etc. The HAL equivalent is a 'component' or 'HAL component'. (This + document uses 'HAL component' when there is likely to be confusion with + other kinds of components, but normally just uses 'component'.) A HAL component is a piece of software with well-defined inputs, outputs, and behavior, that can be installed and interconnected as needed. @@ -139,7 +144,7 @@ Parameter:: accessed. For example, servo amps often have trim pots to allow for tuning adjustments, and test points where a meter or scope can be attached to view the tuning results. HAL components also can have such - items, which are referred to as "parameters". There are two types of + items, which are referred to as 'parameters'. There are two types of parameters: Input parameters are equivalent to trim pots - they are values that can be adjusted by the user, and remain fixed once they are set. Output parameters cannot be adjusted by the user - they are @@ -147,8 +152,8 @@ Parameter:: Pin:: (((HAL Pin)))Hardware components have terminals which are used to - interconnect them. The HAL equivalent is a "pin" or "HAL pin". ("HAL - pin" is used when needed to avoid confusion.) All HAL pins are named, + interconnect them. The HAL equivalent is a 'pin' or 'HAL pin'. ('HAL + pin' is used when needed to avoid confusion.) All HAL pins are named, and the pin names are used when interconnecting them. HAL pins are software entities that exist only inside the computer. @@ -156,13 +161,13 @@ Physical_Pin:: (((HAL Physical-Pin)))Many I/O devices have real physical pins or terminals that connect to external hardware, for example the pins of a parallel port connector. To avoid confusion, these are referred to as - "physical pins". These are the things that âstick outâ into the real + 'physical pins'. These are the things that 'stick out' into the real world. Signal:: (((HAL Signal)))In a physical machine, the terminals of real hardware components are interconnected by wires. The HAL equivalent of - a wire is a "signal" or "HAL signal". HAL signals connect HAL pins + a wire is a 'signal' or 'HAL signal'. HAL signals connect HAL pins together as required by the machine builder. HAL signals can be disconnected and reconnected at will (even while the machine is running). @@ -181,11 +186,11 @@ Type:: - s32 - a 32 bit signed integer, legal values are -2,147,483,647 to +2,147,483,647 -Function::[[des:Function]](((HAL Function))) +Function:: Real hardware components tend to act immediately on their inputs. For example, if the input voltage to a servo amp changes, the output also changes automatically. However - software components cannot act "automatically". Each component has + software components cannot act 'automatically'. Each component has specific code that must be executed to do whatever that component is supposed to do. In some cases, that code simply runs as part of the component. However in most cases, especially in realtime components, @@ -193,13 +198,13 @@ Function::[[des:Function]](((HAL Function))) example, inputs should be read before calculations are performed on the input data, and outputs should not be written until the calculations are done. In these cases, the code is made available to the system in - the form of one or more "functions". Each function is a block of code + the form of one or more 'functions'. Each function is a block of code that performs a specific action. The system integrator can use - "threads" to schedule a series of functions to be executed in a + 'threads' to schedule a series of functions to be executed in a particular order and at specific time intervals. -Thread::[[des:Thread]](((HAL Thread))) - A "thread" is a list of functions that +Thread:: + A 'thread' is a list of functions that runs at specific intervals as part of a realtime task. When a thread is first created, it has a specific time interval (period), but no functions. Functions can be added to the thread, and will be executed @@ -299,8 +304,7 @@ halgui:: GUI tool for configuration and tuning (not implemented yet). halmeter:: - (((halmeter))) A handy multimeter for HAL signals. See section - <<sec:Halmeter>>. + (((halmeter))) A handy multimeter for HAL signals. See section <<sec:Halmeter>>. halscope:: (((halscope))) A full featured digital storage oscilloscope for HAL @@ -308,131 +312,6 @@ halscope:: Each of these building blocks is described in detail in later chapters. -== Tinkertoys, Erector Sets, Legos and the HAL[[sec:Tinkertoys]] |